5 ms·
A bird's eye view on API development
- PierreLechelle 11y agoGreat into on API development. Thanks for sharing :)
- TheEdonian 11y agoThanks for reading ;)
- kbaijnath 11y agoI really enjoyed the article as well. I wasn't even aware of some of the structure standards you listed (specifically JSend and HAL). Side note: I think there is a typo near the bottom trough should be through in the header based versioning section.
- sinzone 11y agoNo mention of swagger?
- hannesvdvreken 11y agoCan't mention everything, right?
- miseg 11y agoThe elephant in the room for me is that while HATEOAS is mentioned, the impression I get from posts from developers online is that people program against a pre-agreed API format. That's different to REST's automated discoverability for REST API clients.
- spdionis 11y agoIn my experience for most REST APIs use cases HATEOAS is not needed or not that useful. Writing a REST API for your mobile application? What do you need HATEOAS for? Do you really think it can replace documentation? On the other hand all the rest of nice bonuses of REST APIs are very useful in such a use case.
- miseg 11y agoExactly, that's where most implementations seem to decide against REST. I agree with you. The other parts of REST (if you agree that REST can be picked apart and still referred to as RESTful), as surely valuable.
- JackuB 11y agoBuilding SPA using Siren, it can be really useful for disabling parts of UI - when you have complex rules on whether user can list/edit/create resource, you just check if such action is in response and use its options. Yes, you can do same with bool flags in response, but if you structure all your decision making like this (around Resources and actions) it's quite easy and natural to make all your components react to un/availability of resource/action, thus accomodating even more complex scenarios - user can list, edit (only some), but can't create new.
- seivan 11y agoGood article, summarise what I like and don't like. I wish it would delve deeper into versioning with some code samples. The way I've done it in the past is just inherit from a controller and just override an action as well as the json-builder. But that because unmaintainable after version 3 or so. I like how Relay/GraphQL sorta abstracts that away, but Ive had a hard time figuring out how to make that work with the ORM (Active Record) so abandoned for now.
- TheEdonian 11y agoI know, this is just an introductory article. You can always take a look at this great book for more info: https://leanpub.com/build-apis-you-wont-hate https://leanpub.com/build-apis-you-wont-hate
- christogreeff 11y agoNice read. Sidenote: Should credit not be given for the use of the xkcd comic?
- TheEdonian 11y agoYou are totally right. Fixed it.
- Omnipresent 11y agoThis is a great guide. Side note: Is there an example of implementing OAuth2 from API developers perspective and from API Consumers perspective? language agnostic but Go or Java preferred.
- TheEdonian 11y agoI haven't seen it myself, but I hear: Google I/O 2012 - OAuth 2.0 for Identity and Data Access (https://www.youtube.com/watch?v=YLHyeSuBspI https://www.youtube.com/watch?v=YLHyeSuBspI) is a great talk.
- johns 11y agooauthbible.com
- Omnipresent 11y agoThis is a great guide. Side note: Is there an example of implementing OAuth2 from API developers perspective and from API Consumers perspective? language agnostic but Go or Java preferred.
- tomp 11y agoCan anyone explain why using different verbs (PUT, PATCH, ...) is preferable to using just POST with an additional parameter (e.g. POST action="add")? It seems like the author's distinction between POST, PUT and PATCH seems rather arbitrary...
- creshal 11y agoYou can use the same end point for all possible actions on an object, instead of having to define different ones, and it standardizes which actions are available where. (Otherwise, is it /wombat/1/edit or /wombat/edit/1/ or /wombat/1/?action=edit or …) There's no disadvantages to using HTTP verbs over anything else. > It seems like the author's distinction between POST, PUT and PATCH seems rather arbitrary... PATCH is… awkward, and probably should be ignored. POST always creates a new resource, under an URL picked by the server. PUT creates or updates a resource under an URL picked by the client.
- snarfy 11y agoPOST action="add" is not RESTful. It's procedural. It doesn't take advantage of all the http caching mechanisms that come into play with the web that you get for free with a resource based design. You should PUT the resource.
- tomp 11y ago> POST action="add" is not RESTful. It's procedural. Can you expand on what you mean by this? In particular, how could HTTP catching mechanism work with POST requests, if the purpose of POST is to change something on the server (so the request should always reach the server)? And in what way is PUT handled differently (by browsers, by proxies, by servers)?
- mnutt 11y agoIt's just conventional. If a PUT fails, you (and others) know you can safely retry it multiple times without having to worry about it having any other effects, like duplicate rows. The concept is called idempotence.
- Cakez0r 11y agoWhy is it considered best practice to use the content type header for API versioning? It always seemed like a hack to me. Url versioning makes much more sense if you consider that your API is a resource and the content of your API is a subresource. E.G. GET /v1/post/1/comment/456 would be semantically equivalent to "give me comment with id 456, which belongs to post with id 1, which belongs to api of version 1".
- subliminalbrad 11y agoThe URL is meant to represent a specific resource. You're requesting a comment resource, not a version of a comment resource. It's semantically inappropriate and may lead to unnecessary complexity. There is an HTTP concept created specifically for this idea. Why not use it?