Improving the tutorial "Developing a RESTful API with Go and Gin"

[Ben Hoyt]

Hi Go team,

I recently stumbled across the tutorial article "Developing a RESTful API with Go and Gin" (https://golang.org/doc/tutorial/web-service-gin), and it seems to me there are a few areas for improvement. I've detailed these in an article I'm planning to publish soon (https://benhoyt.com/writings/web-service-stdlib/), but in short:

1) It's odd to me that official documentation uses Gin (one of many web frameworks), rather than showcasing the Go standard library. It'd be a few more lines of code, but not many.

2) The in-memory database implementation isn't concurrency-safe. I realize it's "just" a tutorial, but it'd be nice if the code at least wasn't buggy (it just needs a mutex around accesses to "albums").

3) There's no validation when adding albums, allowing things like empty IDs, duplicate IDs, and so on.

4) Other things that may be out of scope for the tutorial: for example defining a Database interface to provide a separation of concerns instead of mixing "database" code in with the handlers.

I noticed that the change when this was submitted (https://go-review.googlesource.com/c/website/+/332349) doesn't have any review comments -- it was +2'd by Russ. Maybe it was reviewed elsewhere?

Is there any interest in making any or all of these improvements? Or moving from Gin to the stdlib? I'm not saying to use my version directly, as I think that's more than what would be needed in a tutorial like this, but I think it'd be good to at least consider updating it to fix the race condition. Optionally, we could add validation, consider using only the stdlib, and make some of the other updates I've done in my version.

After discussion of what's in scope, I'd be interested in submitting a CL.

Thoughts?

-Ben

[Seth Bunce]

My $0.02.

When looking at the other tutorials, the gin tutorial does stand out as being different. Will some people interpret the presence of the gin tutorial as a recommendation to use gin instead of net/http (where features overlap)? I've observed that people coming from other languages sometimes assume that net/http shouldn't be used, because the standard library in the language they're coming from has basically deprecated its http support. It is unusual among programming languages that go has had a useful http package in the standard library for over a decade.

Moving gin to the standard library seems like it should be avoided because it would impose major limitations on the gin project because of the go1 compatibility guarantee. I feel like if there is an issue with the scope of the gin tutorial it could be resolved with an extra sentence or two at the top of the tutorial. Maybe something like, "Gin is a popular third party web framework that some people use in addition to the standard net/http package."

Apart from the scope issue, you definitely found some bugs in the tutorial which seem like they should be fixed.

--
You received this message because you are subscribed to the Google Groups "golang-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to golang-dev+...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/golang-dev/CAL9jXCEQbye2hgSZ4TGd_%3DL6ZVH2Q5S6SacT5dhT8xq5J%2BoqYA%40mail.gmail.com.

[Kevin Burke]

I think all four of the changes you mentioned would be good (maybe for 3, just add "// error checking goes here" on one line, or something).

At the bottom we could provide a list of common Go middlewares/http frameworks that people use, maybe.

[Eltjon Metko]

Nice write up Ben, However there is still one thing that In my opinion all tutorials of developing RESTFul APIs (or Web in general) are missing is specifying sensible Timeout defaults for the HTTP Server. While It's reasonable that the default Http Server in the standard lib does not have these timeouts set because it can be used in various settings, I think in a (as close as possible) official tutorial for Web developement this should be made clear and sensible timeouts should be set.   

[Russ Cox]

Hi Ben,

On Sun, Nov 14, 2021 at 2:54 AM Ben Hoyt <ben...@gmail.com> wrote:

I recently stumbled across the tutorial article "Developing a RESTful API with Go and Gin" (https://golang.org/doc/tutorial/web-service-gin), and it seems to me there are a few areas for improvement. I've detailed these in an article I'm planning to publish soon (https://benhoyt.com/writings/web-service-stdlib/), but in short:

1) It's odd to me that official documentation uses Gin (one of many web frameworks), rather than showcasing the Go standard library. It'd be a few more lines of code, but not many.

This was the first of a couple of tutorials we have planned that make use of Go's third-party package ecosystem. The intent was to highlight packages that are widely used and simplify common use cases. It's true that the tutorial would be only a few more lines, but Gin of course has many other things too.

 

2) The in-memory database implementation isn't concurrency-safe. I realize it's "just" a tutorial, but it'd be nice if the code at least wasn't buggy (it just needs a mutex around accesses to "albums"). 

3) There's no validation when adding albums, allowing things like empty IDs, duplicate IDs, and so on.

4) Other things that may be out of scope for the tutorial: for example defining a Database interface to provide a separation of concerns instead of mixing "database" code in with the handlers.

I think all of these are all out of scope for this specific tutorial. A real system wouldn't use an in-memory database at all, so the lack of locking around the in-memory database doesn't seem like a significant problem. The same is true for validation of albums, etc. The goal of a tutorial is to be short and narrowly focused on illustrating a specific idea, in this case a RESTful JSON-based API. It intentionally omits all the input validations, authentication, and other complications that would be present in a real system. All the things you are talking about are good points to highlight, and I'm grateful you took the time to write your blog post, but they would detract from the narrow focus if added to this specific tutorial.

 

I noticed that the change when this was submitted (https://go-review.googlesource.com/c/website/+/332349) doesn't have any review comments -- it was +2'd by Russ. Maybe it was reviewed elsewhere?

Yes, it was. Steve Traut and I do most of the back and forth on these in Google Docs, because that's much easier for reviewing writing.

 

Is there any interest in making any or all of these improvements? Or moving from Gin to the stdlib? I'm not saying to use my version directly, as I think that's more than what would be needed in a tutorial like this, but I think it'd be good to at least consider updating it to fix the race condition. Optionally, we could add validation, consider using only the stdlib, and make some of the other updates I've done in my version.

Thanks for the offer, but we'd rather leave the tutorial as it is. We'd also rather leave the standard library as is. One of the goals for the standard library is to enable third-party packages like Gin rather than try to have a single canonical one. This scales better - the problem with a single canonical one is that there is intense pressure to add everything everyone needs to that single implementation. If we can enable multiple possibilities maintained outside Go, as http.Handler did, then that lets people work independently and avoids the pressure on a single implementation. I talked some about this in my 2015 Gophercon talk: https://go.dev/blog/open-source.

Thanks.

Best,

Russ

[ben...@gmail.com]

Thanks, Russ -- that's all very fair enough.

I still think that it'd be good to at least mention the concurrency issue. For a start, as an experienced developer, that was quite distracting to me :-). But also, given the way beginners often (quite reasonably) learn by copying, I think it'd be good not to have a bug in the code. Or you could call it out when you note that "To keep things simple for the tutorial, you’ll store data in memory."

As others (and one friend off-list) have also expressed surprise about the tutorial using one specific third-party library here, I wonder if we could add a sentence to the tutorial's intro with basically what you've said: that you're not particularly singling out Gin here, but this is one of many tutorials that make use of 3rd party packages.

In any case, I've published my blog post now ... but with a significantly altered intro paragraph quoting your reply to show why it was done that way. Thanks!

-Ben