Understanding REST: Verbs, error codes, and authentication

Question

I am looking for a way to wrap APIs around default functions in my PHP-based web applications, databases and CMSs.

I have looked around and found several \"skeleton

Answer 1

REST Basics

REST have an uniform interface constraint, which states that the REST client must rely on standards instead of application specific details of the actual REST service, so the REST client won't break by minor changes, and it will probably be reusable.

So there is a contract between the REST client and the REST service. If you use HTTP as the underlying protocol, then the following standards are part of the contract:

• HTTP 1.1
  • method definitions
  • status code definitions
  • cache control headers
  • accept and content-type headers
  • auth headers
• IRI (utf8 URI)
• body (pick one)
  • registered application specific MIME type, e.g. maze+xml
  • vendor specific MIME type, e.g. vnd.github+json
  • generic MIME type with
    • application specific RDF vocab, e.g. ld+json & hydra, schema.org
    • application specific profile, e.g. hal+json & profile link param (I guess)
• hyperlinks
  • what should contain them (pick one)
    • sending in link headers
    • sending in a hypermedia response, e.g. html, atom+xml, hal+json, ld+json&hydra, etc...
  • semantics
    • use IANA link relations and probably custom link relations
    • use an application specific RDF vocab

REST has a stateless constraint, which declares that the communication between the REST service and client must be stateless. This means that the REST service cannot maintain the client states, so you cannot have a server side session storage. You have to authenticate every single request. So for example HTTP basic auth (part of the HTTP standard) is okay, because it sends the username and password with every request.

To answer you questions

1. Yes, it can be.

   Just to mention, the clients do not care about the IRI structure, they care about the semantics, because they follow links having link relations or linked data (RDF) attributes.

   The only thing important about the IRIs, that a single IRI must identify only a single resource. It is allowed to a single resource, like an user, to have many different IRIs.

   It is pretty simple why we use nice IRIs like /users/123/password; it is much easier to write the routing logic on the server when you understand the IRI simply by reading it.

2. You have more verbs, like PUT, PATCH, OPTIONS, and even more, but you don't need more of them... Instead of adding new verbs you have to learn how to add new resources.

   activate_login -> PUT /login/active true deactivate_login -> PUT /login/active false change_password -> PUT /user/xy/password "newpass" add_credit -> POST /credit/raise {details: {}}

   (The login does not make sense from REST perspective, because of the stateless constraint.)

3. Your users do not care about why the problem exist. They want to know only if there is success or error, and probably an error message which they can understand, for example: "Sorry, but we weren't able to save your post.", etc...

   The HTTP status headers are your standard headers. Everything else should be in the body I think. A single header is not enough to describe for example detailed multilingual error messages.

4. The stateless constraint (along with the cache and layered system constraints) ensures that the service scales well. You surely don't wan't to maintain millions of sessions on the server, when you can do the same on the clients...

   The 3rd party client gets an access token if the user grants access to it using the main client. After that the 3rd party client sends the access token with every request. There are more complicated solutions, for example you can sign every single request, etc. For further details check the OAuth manual.

Related literature

• Architectural Styles and the Design of Network-based Software Architectures
  Dissertation of Roy Thomas Fielding (author of REST)
  2000, University of California, Irvine
• Third Generation Web APIs - Bridging the Gap between REST and Linked Data
  Dissertation of Markus Lanthaler (co-author of JSON-LD and author of Hydra)
  2014, Graz University of Technology, Austria