EnglishIt’s probably safe to say that REST (REpresentational State Transfer – originally described by Roy Fielding) is the most widely used architectural pattern when it comes to APIs in web application contexts.
From statelessness, to self-descriptive messages, and hypermedia as the engine of application state (HATEOAS) REST comes with quite a few principles, constraints, patterns, and flavours, not all of which are used or applied consistently with each REST API. REST often is a rather loosely-applied architectural pattern or a continuum, on which APIs can be located according to the degree by which they follow REST (or: RESTful) principles (see the Richardson Maturity Model).
Mind you, there’s nothing wrong with that! There’s no point in adhering to a specific principle, pattern, or constraint if it doesn’t make sense for your use case. If all you need is for resources to be accessible via HTTP there’s no reason to dogmatically stick to principles just for the sake of it.
However, it’s a good idea to occasionally revisit these principles and the best practices that come with implementing them in order to review your designs and check your implementations for possible flaws as well as potential improvements.
Recently, John Au-Yeung published an article titled “Best practices for REST API design” that allows you to do just that.
From using JSON as payload format to security considerations, this article has you covered. Among other aspects, it deals with matters such as:
- using nouns in path names (because RESTful URLs represent resources rather than actions)
- nesting resources
- graceful error handling
- filtering and pagination
- caching
- API versioning