wtorek, 22 stycznia 2019

REST API cook book

Introduction


Recently I've stumbled upon an interesting site - REST Cook Book. As nowadays almost everyone develops RESTful APIs and there is a great deal of controversy regarding how to design it properly (say: singular vs plural nouns or collections range query) I decided to take a look at the "recipes" Author serves.

The recipes


First of all, the site is NOT a REST API design guide. Instead, Author decided to write a bunch of short articles concerning some interesting pieces of frequently asked questions. Second of all, Author seems to be focused on HATEOAS (Hypertext As The Engine Of Application State) which differs a bit from "JSON with RPC" style as commonly found in modern Java web applications. The most important difference is that HATEOAS does not care so much about URL structure, as each possible operation for a resource (in other words - possible transition from current state) is returned in form of link / rel / href.
Nevertheless it's an interesting read. Typically authors write a lot about the basics - like mentioned singular vs plurals or how to use basic HTTP methods. Here, we get recipes concerning such rarely discussed aspects as:

  • collection pagination - with link rel = next / first / last 
  • discovering supported HTTP methods with "OPTIONS" 
  • implementing asynchronous operations using 202 "ACCEPTED"
There is also a lot of discussion under almost every recipe, which is very resourceful. 


Brak komentarzy: