For accessing and implementing remote services in applications, software developers have two alternative protocol choices for developing APIs. The first (and the older) option is to go with SOAP (Simple Object Access Protocol) APIs, which fetch data as services. For public APIs in particular though, this approach is no longer that popular. In a recent survey, it was found that 7 out of every 10 public APIs follow the REST (Representational State Transfer) protocol to access web services from the cloud. Not surprisingly, the focus of professional API providers have shifted towards making RESTful APIs, with SOAP APIs gradually receding to the background. In today’s discourse, we will deal with some handy tips for effective RESTful API development:

1. Using GET for state alteration is a mistake

   This one is a big no-no. In order to make changes in state (or changing states altogether), the POST, PUT or DELETE methods should be used. Calling GET for this purpose is likely to generate errors. New API developers need to have a thorough idea about the functionalities of all the REST API methods before starting to code for interfaces.

2. Avoid relying on only top-level resources

   You need to keep your APIs simple, and introducing subresources is a great way of doing that. This is particularly important for interfaces that involve a large number of relationships – where using only the top-level APIs can be complicated. In general, any resource that is a part of another (parent) resource can be used as a subresource. These subresources offer two-fold benefits: firstly, within the representation of the resource, the dependency on individual keys is brought down. Also, API customers can understand the resources more easily, when subresources are present. To put it simply, subresources significantly enhance the readability of RESTful APIs.

Note: Most aggregations can also be included as subresources. Make sure that all subresources are located within their respective parent resources.

3. Versioning is important

   Version changes in an API can be broadly classified under two heads. Firstly, there are the minor version changes, which involve alterations that can potentially affect the performance of the API (for instance, adding HTTP headers on API calls). Secondly, there are major version changes like wholesale changes in the core functionality of the API and/or an overhaul of the URL. Both types of changes can cause loss of service for existing API customers, unless versioning is present. With a systematic versioning system in place (for major and minor changes) you can easily make and track changes in the API – as and when required, without affecting current users.

4. Nouns YES, Verbs NO

   Unlike SOAP APIs, RESTful APIs make data available as ‘resources’. In such a resource-oriented ecosystem, all elements of the API domain (right from Sales and Clients, to Orders, Documents and Users) should be considered as separate ‘entities’. This, in turn, means that nouns – and not verbs – have to be used in the URL (e.g., POST abc.com/trainings instead of POST abc.com/gettrainings). Verbs can be delegated systematically with the HTTP verbs. Each resource needs to be exposed by an API, doing away with the difficulties of actually making endpoints of each specific ‘action’. The HTTP verbs will indicate the action to be performed, while the resources as nouns in the URL will highlight the purpose/functionality.

5. Keep the URLs simple

   Part of the age-old KISS principle for software development. The more complex a URL is, the difficult it becomes for: a) the providers to make changes in the API, and b) the third-party app developers to use the API. The problems tend to go up further if the number of ‘relationships’ represented in the URLs is relatively large. That’s precisely why it is advisable to make use of designated query strings that would keep things simple, and make the URL more intuitive for the customers. A good approach for doing this is adding all value objects within the query string, and the entities just before the string (the Domain Design Driven approach).

Note: Avoid going beyond 3 levels of relationships (parent-child) in the URL. For deeper relationships, using query strings is recommended.

6. Specify communication format in HTTP header

   The format of communication should be clearly mentioned in the HTTP header of a REST API. The serialization formats help both the API clients as well as the API developers to understand how communications/network requests would take place through the interface. For listing out all the supported response formats, use ‘Accept’. ‘Content-type’, on the other hand, specifies the exact format of the request. Confusions over the data communication format can seriously hamper the overall usability of a new API.

7. Design for the user

   Instead of mechanically using the database-driven approach to create RESTful APIs, take time out to jot down the core features and capabilities of the interface first (along with its requirements). In many cases, you will find that using microservices is a much better solution than the traditional database-oriented method. Ideally, an application should have separate bounded contexts, with their implementation not being exposed to users. Customers who need to interact with a specific section/feature of your API should have access only to the corresponding bounded context (making all the data available to everyone makes no point). You need to focus on developing a minimalistic interface that delivers all the desired features, without ever posing a problem for the API customers. User-experience matters in a big way!

Note: The underlying resource(s) in a REST API might be rather too complicated for users. The onus is on API providers to generate a more user-friendly representation of these resources.

8. Make the HTTP verbs idempotent

   While using any of the HTTP verbs in a RESTful interface (GET, POST, PUT, PATCH or DELETE), there should never be any uncertainties over the likely outcome. This is where the importance of HTTP verb idempotency comes into the picture. Check and double-check that all the methods generate the same results every time, irrespective of the frequency or the number of times they are being called. Remember that all API calls come with a certain expectation on the part of the user – and unless the methods in your API are consistent/idempotent, it won’t be able to fulfill these expectations. The API will suffer as a result.

9. The importance of HATEOAS

   Yet another factor that can trip up an otherwise good REST API is an over-complicated navigation scheme. HATEOAS, or Hypermedia As The Engine Of Application State, is a principle that addresses this issue well – and hence, should be utilized during the API designing phase. In essence, the HATEOAS approach is all about placing properly working (pre-tested) hypertext links to facilitate smooth navigation within the interface. The use of hypermedia in RESTful APIs is already increasing across the world, and it does offer important advantages.

10. Use plurals in endpoint names for accessing resource

    This is more of a matter of developer as well as customer convenience. While using plurals for every single resource does not seem correct from a strict grammatical point of view – there are other key advantages of using them over the singular forms (and API developers need not be overtly bothered about grammar in their codes any way!). The use of plurals (e.g., api/users instead of api/user) gives a clear indication of the entire collection of data that needs to be fetched (in our case, ‘user’). Barring a few exceptions, plurals should be used for most resources.

Note: The use of plurals in endpoints is not a rule per se. The important thing here is to avoid mixing up singulars as well as plurals at the different endpoints in the same API. Plurals are generally preferred since they make the APIs more intuitive.

         11. Go for security

API security is one of the most hotly debated topic among software and networking professionals globally. In any REST API, the presence of a valid SSL layer is an absolute must – to remove the risks of unauthorized data access, theft and/or modification. Keep in mind that all that it takes to access a web API is a terminal with a stable internet connection – and not all such connections are secure (at certain points, the data encryption can be incomplete, or worse still, absent). With SSL, all data stored and transferred in the API remain encrypted and organized. In addition, process of user-authentication also becomes simpler. Instead of signing each API call request separately, generalized access tokens can do the trick.

       12. Each resource should have two base URLs

The need for this might not be apparent at first – but it is very important nonetheless. API designers should create 2 separate base URLs corresponding to each resource. One of them will be handling specific (single) values, while the other will be for managing multiple values. This approach helps users keep track of their network requests on a real-time basis. Relying on a single URL for both specific and multiple values increases the chance of errors being returned.

        13. The camelCase vs snake_case debate –

Whether you should use camelCase or snake_case to name the fields depends entirely on the programming technology you are using. As a rule of thumb, use snake_case while working with Ruby and Python, and switch over to camelCase when you create APIs with Java or C#.

Note: According to an eye-tracking study, snake_case is around 20% more easily readable than camelCase. The former is extensively used for JSON APIs.

Bonus Tip: Sometime in 2011, JSON APIs overtook XML APIs in terms of popularity (as per Google Trends). JSON is a leaner, easier-to-parse and easier-to-read tool for data interchanging and access than XML. Unless you are building a REST API that would be widely used by enterprises, it’s better go for JSON-only interfaces.

While working on proxies that do not support all the HTTP verbs (there are some that support only GET and POST), a X-HTTP-Method-Override custom header is required. Choose the underlying API style carefully, and follow standard naming conventions (everything has to be intuitive). It’s important that you follow these best practices for RESTful API development – to ensure that your software indeed delivers the desired solution.