Watching – Beautiful REST & JSON APIs
A nice talk on designing REST JSON API. REST is becoming the API standard in web world, but there’s no strict ‘standard’ and there’re many different styles of implementation. This talk discusses about several guidelines to be cared.
- REST is easy for consumers, but there’s difficulty for providers. One reason is there’s no standard. There’s no RFC, and it’s just based on styles and patterns. Everyone interprets them in slightly different ways.
- Resource can be classified as instance and collection. Collection resource should be named as plural (ex. applications), and may have child instance.
- Behavior can be defined with HTTP verbs like GET, POST, etc. The meaning of POST and PUT are not obvious, and these can be used for both creating and updating resource. One note is that PUT operation needs to be idempotent. When it’s used for creating resource, all the parameters need to be supplemented for achieving the same results. POST doesn’t require to be idempotent.
- (around 39:00) There’s different ways to express link to another resources. XML has standard, but JSON does not. One recommendation is to just use the simple “href” attribute.
- (around 42:00) Having resource expansion feature can reduce the number of requests. optional parameter can be used to list up additionally embedded attributes.
- For authentications, avoid sessions and make it stateless. Check on resource contents rather than specific URL, as it can change or can be redirected.