Reddit reviews RESTful Web APIs: Services for a Changing World

Hi, I'd love to give you some honest feedback on REST APIs and how you've implemented yours.

Have you read any documentation on building REST APIs before? How to use HTTP methods and correctly build URIs? Obviously, REST is a set of guidelines and not a standard, so you haven't done anything wrong, but your API is currently not very REST-like at all. Allow me to explain:

1. REST should use HTTP methods to perform CRUD (Create, Read, Update and Delete) functions on resources / models in an application. These map to the GET, POST, PUT and DELETE methods in HTTP. Currently, your API does not conform to this. You are using HTTP POST on a GET method here, for example.
   
   
2. Your URIs (URLs) should be formatted like this: /token and not /get_token. Your HTTP METHOD already defines the action you want to perform on the token.
   
   
3. Most REST APIs have decoupled resources, so instead of being able to get the page from a book with a single URL, you should be providing a hypermedia link as an attribute in the returned data of a book resource that links to a list of page resources. Obviously this isn't always practical, and your API might work better this way.
   
   The main points I'm trying to emphasise here is that REST is not a standard, but it is still a set of guidelines and REST APIs do not just mean you're using HTTP. Now - your API might work perfectly with good documentation and great for you (you built it, after all). Just consider the naming of the type of API before you share it. Someone who sees "this is a REST API" will be in for a shock because some parts of your API is not.
   
   For further reading, I'd recommend RESTful Web APIs