RESTful Web APIs

What Hacker News says

1. brigandishMar 2022
   The classic book on the subject is RESTful Web APIs[1], and it spends a while explaining HATEOAS by using the example of the web as we've come to expect it as the exemplar REST API using HATEOAS. I also have this essay[2] on HATEOAS in my open tabs, and it uses the example of a web browser fetching a web page.

   [1] https://www.oreilly.com/library/view/restful-web-apis/978144...

   [2] https://htmx.org/essays/hateoas/

   thread
2. irene_tFeb 2021
   Hey, check out this book, should be helpful https://www.amazon.com/RESTful-Web-APIs-Services-Changing/dp...
   thread
3. macca321Apr 2019
   There's two kinds of REST. REST as most developers misunderstand it, and REST as Roy Fielding, inventor of REST, understands it.

   For the former you can read the Microsoft REST guidelines, for the latter I suggest getting Mike Amundsen's RESTful Web APIs book.

   If you do go with the latter be prepared for a lot of frustration with those who went with the former.

   thread
4. JimDabellMay 2018
   It's pretty simple – the information a client needs to transition from one state to another needs to be encoded in the documents. So if you were to design a garage door opener, a non-REST specification might say something like:

       To get the door status, GET https://example.com/status  
       
       To open the door, POST to https://example.com/open  
       
       To close the door, POST to https://example.com/close
   

   A REST approach might use a document something like this:

       {
           "doorState": "closed",
           "actions": [
               {
                   "label": "Open the door",
                   "href": "/open",
                   "method": "POST"
               }
           ]
       }
   

   Then, upon a client performing an "Open the door" action, the server would then respond with a document like this:

       {
           "doorState": "open",
           "actions": [
               {
                   "label": "Close the door",
                   "href": "/close",
                   "method": "POST"
               }
           ]
       }
   

   …and vice-versa. So at any given point, the web service is describing to the client what the state is and how to transition to other states. There's quite a few different benefits to doing it this way – for instance, if you wanted to add a "Turn the garage light on" feature, you could just add the action into the API and clients would be able to use it without any changes whatsoever. Or if you wanted to disable an action, you'd simply remove it from the actions array and the client wouldn't present it to the user as an option. Want to A/B test different label text? You don't need any special A/B testing functionality in the client, just vary the responses you send to users and observe which actions they take. Want to translate into different languages? Just take a look at the Accept-Language header coming from the client and respond with the right label text.

   In practice, you'd want to use a vocabulary that's already out there like Hydra instead of coming up with your own format. But it can sometimes take a little time to get up to speed with them because they are necessarily quite flexible. But you can get most of the way there by simply thinking about it in terms of "the server tells the client what to do and how to do it".

   For something as simple as a garage door that you are certain will never need to change? The benefits REST brings probably aren't going to be worth much to you. But as the complexity of an API grows, the point at which it's easier to use REST than not arrives very quickly.

   If you want to read more about this, the best book I've found on the subject is RESTful Web APIs: http://restfulwebapis.com/

   Show morethread
5. JimDabellAug 2016
   I think it depends on what type of API you'd like to design.

   If you're talking about REST APIs, then the best book I've come across is RESTful Web APIs by Leonard Richardson and Mike Amundsen:

   http://restfulwebapis.org/

   It actually shows you how to do REST properly, not that shoddy knock-off REST that some people push, where you have to document all your URI structures and hard-code them in your clients. There's solid examples that you build upon throughout each chapter, and jumping off points to standardisation work like JSON-LD etc.

   Show morethread
6. tom_bNov 2014
   Yes. As a hacker who leans on books, blogs, and well-defined principles, RESTful api design resources have often been much more http RPC oriented.

   Hackers should pay attention to:

   http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...

   I have also found collection+json and hypermedia application language (HAL) to be useful.

   Plus, I have spent a bunch of time reading the Restful Web APIs book from O'Reilly. Useful for me, as a relative newbie, in providing some logical foundation to start from . . .

   Show morethread