There are many good online resources that you can refer to to help you understand the best practices in relation to API Design. Use this resource to help build up your foundational understanding of REST. Here is a particularly good article on RESTful API Design.

Design easy-to-consume APIs

A good API design makes the API easy to consume by the app developer. Below are a set of design best practices that have enabled many API designers with SOAP design experience to build the right set of easy-to-consume RESTful APIs. Using a data-centric model APIs should focus on the underlying entities/resources they expose, rather than a set of functions that manipulate those entities. In other words, the URLs should have nouns, not verbs.

For example, a collection of cars could have a URL https://cartracker.com/cars. And, individual cars would each have a unique URL like http://cartracker.com/cars/9672376. With this approach, you can retrieve the details of the car using the GET method, delete the car using the DELETE method, and modify properties of the car using the PATCH or PUT methods.

By contrast, in a function-oriented API, there is much more variability, and much more detail a developer has to learn. And there is no clear structure or pattern you can use to help them with the next API.

Building simple JSON

Due to its simplicity, JavaScript Object Notation (JSON) has become the de facto standard for web APIs. When JSON is used well, it is simple and intuitive. If your JSON doesn’t look as straightforward as the example below, you may be doing something wrong.

{

“kind”: “Car”
“name”: “BMW”,
“Color”: “Silver”,
...

}

Your JSON API will be simpler and easier to understand if you stick to the principle that the names in your JSON are always property names, and the JSON objects always correspond to entities in your API’s data model.

Expressing relationships as links

If your web APIs do not include links today, a first step is simply to add some links without making other changes, like this:

{ “id”: “12378”, “kind”: “Car” “type”: “BMW”, “Colour”: “Silver”, “ownerID”: “9876599”, “ownerLink”: “https://cartracker.com/persons/9876599” }

Using links makes it easier for app developers to consume resources, with less to learn and no need to hunt for documentation. Moreover, links can be plugged into templates to produce the right URL.

Designing URLs

A good way to make APIs human-friendly involves the creation of entity URLs that have the entity type in them when fetching a specific resource. Thus, instead of https://cartracker.com/RTRX4545666, it is more desirable to have https://cartracker.com/cars/4545666.

Also, it is not recommended to code a hierarchy of entities into an URL. Hierarchies are not as stable as they might seem; encoding them in your URLs could prevent you from reorganizing your hierarchies in the future.

For query URLs, it is recommended to use the format:
https://cartracker.com/persons/{personId}/cars rather than 
https://cartracker.com/search?type=Car&owner={personId}

Many app developer prefer the first format because it is more readable, more intuitive, and easier for API developers to implement.