Why focus on REST API Design ?
The Software industry is making a rapid shift towards REST APIs and for obvious reasons too. I would like to share a few design principles to help you make judicious design decision with regard to your Rest API. Establishing a set of design principles can be of utmost importance to a successful and useful Rest API.
Essence of API Design Principles
When you create a REST API, meeting the expectation of your consumer or clients of your API is your prime focus. A well-designed API should be easily understood and usable by client developers. A well-designed API also allows you to set the objectives clear and concise for the consumer, this helps avoid any misrepresentation or misinterpretation. You need to make the life of your consumer easy, which is how you win more consumers, needless to say !
From Developers standpoint, it should allow for easy maintainability of modules that can stand well against the test of time. Lets see what should your design goals be, which helps you achieve these objectives.
Design Principles and Techniques
(1) Deep Understanding of your API consumers
A detailed knowledge about your users, their platform, programming language and how they would be using your API, is critical. You should know from which device or devices your API would be called from, how the clients would be calling the API, how many end user the client needs to support.
The information helps in designing your API and helps you in evaluating what type of response you should be supporting – XML, JSON or both for instance. It helps you in evaluating how you would be hosting your services, the bandwidth needs, the scalability and performance benchmarks that you would need to set.
A deep understanding of your consumer also helps in taking important decisions like – what functionality you should be supporting as a part of the API and what you should leave for the Client to do.
(2) Efforts should go into proper Resource Modeling
Concepts of REST are closely based on HTTP. HTTP stands for Hypertext Transfer protocol. While using Internet, you issue HTTP request to get a resource from the web, similarly REST is based upon resources.
The API request is made through HTTP method on resources. These resources are nothing but your domain objects that clients need. So, you visualize and expose your domain objects as resources and allow manipulating them with help of HTTP verbs like – GET, POST, PUT, DELETE etc.
Remember always your internal domain objects can be different than what you expose as resource through your API. You should expose only what is necessary
- A proper decision should be made while designing your resource model. For this purpose you may use some of older Data modeling techniques like ER Diagrams.
- Your resource should be in Noun (and not verb) and should be easily understandable by your consumer.
- The resource may or may not have one-to-one mapping with your API internal data model. You should abstract the internal complexity and simplify your API that would be available to the consumers.
- Your resources can fall under different categories. Define your resources as collection, document, Store or Controller. If you need to manage a complex relationship you can model the relationship to a noun as well. Decide judiciously.
- A noun should be a document name.
- Collection should be Noun in plural
- A store should be Noun in plural as well
- A controller should have verb to specify something, which can’t be modeled, as a noun and suggest an action or a procedure kind of construct.
(3) URI Naming – Keep it short, sweet and easy to understand
- Your resources would be addressed using URIs or the Uniform Resource Identifiers.
- You should be careful to keep it short and easy to understand.
Is better than
- Use proper formatting of the URIs, use forward slash to indicate hierarchy and don’t include trailing forward slash at the end of URI like the below.
- Don’t use underscores; use hyphens when necessary to improve readability, prefer lowercase for resources. …to be contd.