REST is paradigm or architectural style that defines your API.

  • One of the most important and yet simple REST consept is resouce/endpoint, I really like resource term so I’m going to use it here. In REST paradigm URL is a resource, e.g. — http://example.org/test/foo.

  • You should strive not to use verbs in URL. The only verbs you need are HTTP verbs — GET, HEAD, POST, PUT, PATCH, OPTIONS, TRACE.

  • Subresource in REST looks like this — /posts/{id}/author. With GET verb it means — fetch me an author of this particular book. It makes no sense to continue a subresouce with additional nesting. If you have situation like this TRY to move that to separate endpoint. Although the correct answer is always — “it depends” : )
    If you are developing something vast and complex e.g. github api than you can/should use longer URLs to fit in all the domain logic.

  • Plan and build API documentaion first. Write your API documentaion with OpenAPI3 and use tools like Prism to create mock API and give it to the client. This way you can get an early feedback, see the full picture before actual development started.

  • If something goes wrong you should use HTTP status codes and custom error codes and messages e.g. twitter error codes. You need to use custom error code because HTTP statuses can not cover all your needs — you have to be more specific about happened errors instead of just sending 500 status with message “Oopps… something went wront”.
    Error codes can be used to take specific measures and act accordingly, for instance if you got smth. like “Your JWT token expired” you can do a login and retry an action.

  • Test your API! You can do this with BDD using Behat or use WebTestCase class provided by Symfony.

  • Versioning could be done with prefixing, e.g. /api/v1, /api/v2 and etc. or version number could be sent in Content-Type HTTP header, like github does it

  • For proper authentication use OAuth2 or JWT. OAuth2 seems to be the best choice as a more “solid” authentication solution. Make sure to read “What Happens If Your JWT Is Stolen?” in the resources section.

  • Make sure to check your HTTP headers. Set all security headers and throw away unnecessary once, check security list under Resources section.

  • HATEOAS makes REST api RESTFUL. HATEOAS means you should use Content-Type header and speak in a language your client requires, be it JSON or XML or plain text for some reason. HATEOAS also means that you should provide related data in the form of links in the response. That related data coulb be use in a form “find me all the frends of that user partner”. These links can help your API to work with your API more efficiently.

Misc:

  • UUID is a must, do not use auto-incrementing ids

  • Store Timezones, not offsets. Use IANA

  • Obvious, but… SSL is mandatory for all communication.

Resources:
Build APIs You Wont Hate by Phil Sturgeon
Build APIs You Wont Hate: Second Edition
What the hell is REST, Anyway? REST API Tutorial
What Happens If Your JWT Is Stolen?
API-Security-Checklist
JSONAPI
GitHub API