Define routes to methods: good practices

Define 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

    • Related Articles

    • Creating API Methods

      Summary In the article Create and manage APIs versions The first necessary steps to create APIs were shown. Methods define the action to be taken on a particular esource. As a first step you should select the option of Add Methodin the API. Add ...
    • Define response formats of methods

      Summary Output formats allow you to define one or more response formats in your API methods. Output formats can be multiple in JSON format, although it can also expose the data in CSV and XML. Configure formats When creating a method you should ...
    • Configure APIs and Methods Privacy

      Summary You can define the privacy of your APIs and methods to grant access only to users you want, or revoke accesses when you require it. Privacy rules You can set up the visibility of APIs and methods, i.e. whether they would be public or private. ...
    • Define personalized error responses

      Summary In the same way you can define formats and templates for successful application responses to a method, you can also define error templates for each format you've added and for each type of known error. Set up custom error templates Creating ...
    • Sharing private methods to registered users

      Summary When you have defined your methods with Private visibility, you shouldshare with registered developers who must haveaccess to the method. Share access Methods can be protected by Keys API or the OAuth2.0 protocol. Methods protected by Keys ...