Rest API Design and Best Practices

The most important part while building any rest api is the api design i.e. URL. Here are the best practices while designing any rest api.

1. Segregate the apis into logical resources:

              In Rest, the primary data representation entity is called resource.  The key principle of rest involve separating your api into logical resources.
               Example: For an e-commerce website, the possible resources can be orders, customers, vendors etc. 

2. Resource names should be a noun (not verb):

                  RESTful URIs should refer to a resource that is a thing (noun) instead of referring to an action (verb) because nouns have properties which verbs do not have – similar to resources have attributes.

                  Example: /employees, /orders, /students, /posts etc. instead of /getEmployees, /createOrders

3. Use HTTP Methods to manipulate the resource:

                   Once you have your resources defined, you need to identify what actions apply to them and how those would map to your API. RESTful principles provide strategies to handle CRUD actions using HTTP methods mapped:
        GET -   To get resource
        PUT -   To create resource
        POST -  To update resource
        DELETE - To delete resource

        Example: Consider a use case of order resource in e-commerce, the possible actions can be getting all the orders, getting order by order id, creating order, update order, delete order etc. All these actions can be justified using HTTP methods as follows:

       GET            /orders           - Get all the orders

       GET            /orders/2        - Get order of id 2

       POST          /orders           - Create an order

       PUT            /orders/21      - Update order for id 21

       DELETE     /orders/12       - Delete order having id 12

4. Deal with relationships between the resources properly:

               In certain scenarios, there can be relations between the resources like -orders associated with customer. RESTful principles provide useful guidance. The orders can be logically mapped to customer endpoint as follows:
       GET     /customers/2/orders.       - Get orders associated with customer having id 2
      GET     /customers/2/orders/12    - Get order with id 12 associated with customer with id 2
      PUT    /customers/15/orders/2     - Update order with id 2 for customer with id 15

5. Versioning the URL:
             To manage this complexity, version your API. Versioning helps you iterate faster when the needed changes are identified. APIs only need to be up-versioned when a significant change is made. These changes include:

• A change in the format of the response data for one or more calls
• A change in the response type (i.e. changing an string to a integer)
• Removing any part of the API.

        How to Version:

         Using the URI is the most straightforward approach (and most commonly used as well). 

         Example: /v1/orders.

         The version can be numeric “v[i]” syntax. You can also use dates or any other identifier that is flexible enough to change as the versions change.