RESTful HTTP API Standards? [closed]

Question

Closed. This question is opinion-based. It is not currently accepting answers.

---

Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.

Closed 8 years ago.

Improve this question

Tasked to detail a simple API, I did a little research and suspect everything I know about the Internet is wrong.

I've Googled for far longer than I care to admit, reading a number of articles, StackOverflow questions and websites that all seem to vehemently disagree. I recognize every developer does things differently, but still suspect there is an official standard somewhere, or at least a general best practice (although, admittedly, not everyone follows whatever the best practice).

This API would use JSON. That I cannot change.

What my local peers do/have told me (very likely incorrect):

• HTTP is a complex, antiquated beast that we should deal with as little as possible. It's simply a vehicle for moving chunks of JSON back and forth, where the magic happens. All data and metadata should be in the JSON, and you can set it up exactly as you like.
• Use a 200 status code for everything, even if there is an application-level error or problem with the user's input. The other error codes mean something went wrong with the HTTP operation--a catastrophic unexpected server error, using the wrong URL, that kind of thing.
• "Envelope" the JSON data for messages from the server; have JSON properties for metadata and include the actual JSON object/array inside a consistent property, like "data"
• HTTPS is "nice to have" but not important for minor projects
• Use PUT requests for everything
• Log in to get a randomized strong of characters as an access token from the server. The server stores information on when the token expires, what account it is for and what IP address used it. Pass that access token to the server for every other call; the client does not store the password.
• URLs tend to be verbs, like /register or /checkout or /changepassword. All other needed data is in the JSON. Each operation has its own URL

What I THINK might be right based on my reading, but not sure

• HTTP is the divine data structure. Header information and server return codes can encompass any possible metadata and is, indeed, designed for that purpose. The contents need only contain the actual JSON object(s) the applications are acting upon. Put nothing in the JSON body that could possibly be part of the HTTP metadata.
• ALWAYS use HTTPS, for everything
• For any possible error (a form field didn't validate, the user's session expired, their game character is dead), send an HTTP status code. Try to pick what seems closest based on the W3C descriptions, but all that really matters is that you use it consistently in your system. The code should be enough to tell the client app what to do (show user validation errors and make them fix form input, make user log in again, take user back to main screen). The body, in case of errors, contains extra details about the error, if necessary.
• The client app should pass login info with every request, in the HTTP header. This means it needs to use basic auth, which means it needs to remember the user's password.
• The JSON data should never be in an "envelope". There is no standard format, because the contents directly represent the object(s) needed for the given operation as indicated by the combination of URL, GET/POST/PUT/DELETE
• URLs tend to be nouns, like /user or /shoppingcart. Subdirectories of the URL refer to the object ID being acted on: /user/johndoe or /shoppingcart/12359. A URL could be used for different operations for GET (retrieve data) POST (update data) PUT (create new data) DELETE (remove data).

I'm not even sure that either of these is fully right--can you tell me the rules for what is the official, or most recommended way to structure such an API?

Answer 1

You should read the relevant part of the Fielding dissertation, that defines what REST is: http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm

Some additional dissertation from Markus: http://www.markus-lanthaler.com/research/third-generation-web-apis-bridging-the-gap-between-rest-and-linked-data.pdf He started the work about creating a standard REST implementation: the http://www.hydra-cg.com/ RDF REST vocab and the http://json-ld.org/ RDF JSON format. Currently we don't have a standard solution to describe the uniform interface of any REST service. This is like if we would not have a HTML standard. That's why we are not able to write REST browsers just application specific clients.

(Hydra is not production ready, I guess they'll need another 2-3 years to standardize it and start to build Hydra specific tools. Until then we cannot really talk about real REST, because most of the APIs define an implementation specific format or use a non-standard more or less common format, like HAL.)