Method defining routes to methods: good practices

Method defining routes to methods: good practices

Summary

Definition of routes orpathsmust be consistent with the resources or entities to which the method refers.

Certain good practices for considering in defining routes.


A review

Before proceeding, let's look at what parts of an endpoint or url. For example:
  1. "api" is the API query subdomain.
  2. "company.com" is the domain of your account.
  3. "Daily indicators" is the name of the API. Remember that the API name would be the item you define when creating the API.
  4. "v1" is the API version. Review the article on versions of APIs.
  5. "dolar" is the name of the API method.
  6. ".json" is the format of consultation to the method. Review the article on output formats.
  7. What follows the question mark "?" are the parameters to be sent, such as auth_key or others required by the method.

Definition of language

Define a language to use for your APIs and methods. We recommend using English if it is your primary language, but you can also use English. What is relevant in this case is to be consistent, the same language should always be used for APIs, methods, attributes, dictionaries, etc.

Method route

When creating a method, you should define your route.



  1. Use plural nouns, not verbs.
  2. Avoid using singular nouns.
  3. Use the same routes for different types of requests.
  4. Do not use accents, spaces or special characters in the URL.
  5. If you want to separate words use the average guide.

Correct examples

Get list of documents in .json format:
  1. Get https://api.empresa.com/api/v1/documents.json

Obtain documents by identifier in .json format:
  1. Get https://api.empresa.com/api/v1/documents/123.json

Create documents
  1. Post https://api.empresa.com/api/v1/documents.json

Incorrect examples

Singular nouns are not recommended:
  1. GET https://api.empresa.com/api/v1/documents
  2. GET https://api.empresa.com/api/v1/document/123.json
Verbs in the URL
  1. POST https://ejemplo.cl/api/v1/application/create

Parameters on the route

If required, you can add the data view parameters on the method path.

By default, the method inherits the parameters of its associated view. For example:
  1. http://api.junar.com/accounts/v1/users.json?auth_key=XXXXX&id=16329928

But it is also possible to add a parmeter on the method path. To do this, you must enter the route to the method on behalf of the key parameter.
For example:
  1. /users/{id}
In this case, the API consultation would have the following structure:
  1. http://api.junar.com/accounts/v1/users/123.json?auth_key=XXXXX