HTTP Method DELETE. Payload: empty.
API Design Guide
41–50 of 192 posts
Re: API Design Guide
#42Fantastic Read! But I am still looking for some books on good API-Design, anybody has any recommendations?
If you don't mind Java, Effective Java by Josh Bloch has good API design material. Josh designed collections API in Java
very good read, but not really about web/http/rest API's.
Re: API Design Guide
#43My biggest pain when designing a rest API is a standard authentication method that won't drive me crazy. So far i've always used 3rd party modules to implement different kinds of authentication but I never quite understood it in depth. Apart from HTTP Basic Auth, but please don't use that.
Basic auth is great. It lowers the barrier of entry, to anyone with a browser.
Not all users of APIs are developers.
Re: API Design Guide
#44I would like to add Microsoft's API Guidelines [1] here, which is also a well written document and can be helpful to anyone designing an API. [1]: https://github.com/Microsoft/api-guidelines/blob/master/Guid...
It's interesting that both of these guidelines kind of reject HATEOAS by mandating explicit versioning. It seems that HATEOAS was never really a thing. It's just too complicated to implement in practice. In that sense, REST in practice has always been just RPC without a clear spec for procedure call like XML or JSON RPC.
It's just never been clear to me what HATEOAS is really supposed to be good for. Sure, a client can follow the links in an automated fashion, but how is it supposed to know what the resources actually are and which links it needs to follow, which resources it has to create or modify, to actually accomplish anything?
The general idea of returning links to related resources and/or actions is fine and good, but the rhetoric tends to go further, to ecompass claims like the API being "self-documenting" or amenable to a universal client. It always seems to me that this Big Idea of just presupposes the existence of a "smart" client that can really understand the links, one that there doesn't seem to be much sign of.
GitHub's API proudly notes its use of hypermedia and URL Templates in its responses, but I still have go read the documentation to decide what link I need to use, and what needs to fill into those variable slots in the URLs. The template doesn't do much for me that text in the documentation saying "these GET paramters are accepted/required" wouldn't just as well.
Re: API Design Guide
#45Seems pretty good. Specifically this part of the guide is pretty well written: https://cloud.google.com/apis/design/resources . One thing that is surprising to me however is that their is no mention of using HTTP Status Codes in responses.
Using HTTP status codes in your responses is a trap. It conflates the API transport with the actual semantics of the API. The goal of HTTP error responses is to say that something went wrong in the transport layer. The goal of API error responses is to say that something went wrong in your service. For example, your HTTP REST server may be perfectly fine, but your back end DB may be misbehaving. Having separate API l…
Our experience, from having gone that route internally and externally (e.g. with JSON-RPC), is that it ends up not paying off to have that separation.
From the client side, developers shouldn't need to worry about what piece of your stack was at fault. They want to know if it's your fault or theirs/their user's. And if it's their fault, how to prevent it or fix it. Both HTTP and gRPC are flexible enough to encode that information.
From the server side, it complicates monitoring in practice if errors are propagated encoded in the response body of a "successful" RPC. With reverse proxies and other things in place, the complication increases, and many people get unhappy.
W.r.t. migrating clients to other transports, the client library should hide that (we haven't done that always right in the past, but we do now).
Re: API Design Guide
#46HTTP Method DELETE. Payload: empty. I know DELETE is not supposed to have any payload, but using PATCH is awkward if you have to delete multiple resources based on a query or a filter. You need to specify a 'delete' action as part of PATCH request which means the payload model has to be different. Just awkward.
You face the same problem if you want to just list multiple resources based on a query or a filter. The solution isn't to send a GET with an HTTP body, which is counterintuitive to most people, and many proxies just drop. It's to make your filter part of the URL (as a query parameter). Same with DELETE.
Re: API Design Guide
#47Earlier quoted context omitted.
It's interesting that both of these guidelines kind of reject HATEOAS by mandating explicit versioning. It seems that HATEOAS was never really a thing. It's just too complicated to implement in practice. In that sense, REST in practice has always been just RPC without a clear spec for procedure call like XML or JSON RPC.
It's just never been clear to me what HATEOAS is really supposed to be good for. Sure, a client can follow the links in an automated fashion, but how is it supposed to know what the resources actually are and which links it needs to follow, which resources it has to create or modify, to actually accomplish anything? The general idea of returning links to related resources and/or actions is fine and good, but the rhet…
> Sure, a client can follow the links in an automated fashion, but how is it supposed to know what the resources actually are and which links it needs to follow, which resources it has to create or modify, to actually accomplish anything?
I've never understood this either. My API client isn't smart enough to follow links and write logic for me, so when they say "the client" can "discover", they must be referring to myself, and not my code? Well I'd much rather read documentation than click hyperlinks inside an API.
Re: API Design Guide
#48Earlier quoted context omitted.
We've been using GraphQL for everything since late 2015. All recent code is GraphQL-first, and all old code is proxied by a GraphQL layer in front of it. Our application helps BigCos to understand if they pay people fairly and to run smart pay reviews. It's a relatively small codebase, ~100k LOC, but it's essential complexity is in managing and connecting dispersed data about employees and markets. GraphQL allows us…
REST describes relationships very well, via hyperlinks. You navigated to this page via a hyperlink. If your API doesn't do that, it's not REST, this is what people usually mean when they point out that an API isn't complying to the REST style.
REST describes relationships just fine. Now return a list of 100 documents that each have a list of related comments. Your client just needs to request
GET /documents
GET /documents/1/comments
GET /documents/2/comments
GET /documents/3/comments
GET /documents/4/comments
GET /documents/5/comments
..
GET /documents/99/comments
GET /documents/100/comments
Re: API Design Guide
#49Earlier quoted context omitted.
It's interesting that both of these guidelines kind of reject HATEOAS by mandating explicit versioning. It seems that HATEOAS was never really a thing. It's just too complicated to implement in practice. In that sense, REST in practice has always been just RPC without a clear spec for procedure call like XML or JSON RPC.
It's just never been clear to me what HATEOAS is really supposed to be good for. Sure, a client can follow the links in an automated fashion, but how is it supposed to know what the resources actually are and which links it needs to follow, which resources it has to create or modify, to actually accomplish anything? The general idea of returning links to related resources and/or actions is fine and good, but the rhet…
Yep. In theory, one could imagine various schemas at various levels of abstractions that allow the client to 'know' what's going on, automatically deriving it from the schemas.
I think this is also the theoretical promise of one approach to linked data/RDF.
In practice, I don't think it happens, and is not worth the conceptual and engineering overhead for the possibility of something that doesn't seem to be realistic to expect.
Re: API Design Guide
#50HTTP Method DELETE. Payload: empty. I know DELETE is not supposed to have any payload, but using PATCH is awkward if you have to delete multiple resources based on a query or a filter. You need to specify a 'delete' action as part of PATCH request which means the payload model has to be different. Just awkward.
A bulk deletion isn't defined as part of their "Standard Methods" .. For stuff that doesn't fit the standard methods, they have this page on custom methods: https://cloud.google.com/apis/design/custom_methods
That said, I'd implement a bulk deletion in one of three ways:
:::: ONE
DELETE /thingies/id1,id2,id3
When all is ok, the response is a 200. However, if one of the deletions fail, how you handle the response is more complicated.
:::: TWO
POST /thingies/bulk_delete
and have your ID's listed in the body. Still same problem with handling the response.
:::: THREE
POST /bulk
Instead of implementing a bulk deletion at all, think about how you can implement "bulk requests" as a higher level feature of the API.
So you can transport a bunch of delete's as part of a single HTTP request, and get back a bunch of response codes packaged into a single response.