Naming your API Endpoints

The naming scheme of your endpoint URLs can help you stay organized and efficient. Below are some things to keep in mind and best practices.

As you begin creating and adding additional endpoints to your API, you should consider being mindful of how they are named. Your naming convention, when done strategically, can be a valuable tool that helps you and others clearly identify and understand which endpoint does what. There are a few things to know about naming your endpoint URLs.

Resources and URIs The primary data representation in REST APIs is called Resources. If Resource naming is consistent and strategic, it makes it easier to understand which API endpoint is doing what.

REST APIs use Uniform Resource Identifiers (URIs) to address resources.

For example, /merchants is considered the URI.

Use nouns instead of verbs You should predominantly use nouns when naming. You should not refer to any of the CRUD verbs (get, delete, post, etc.). HTTP request methods should be used to indicate which CRUD function is performed. “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.” – RESTfulAPI.net

Forward slashes (/) indicate hierarchical relationships The forward-slash (/) character is used in the path portion of the URI to indicate a hierarchical relationship between resources. *Do not use trailing forward slashes (/) as this can be confusing.*

Path parameters Curly brackets {} indicate required path parameters for the API endpoint. They are used to identify a specific resource or resources.

Use lower case letters when convenient By convention, resource names should use exclusively lowercase letters.

Do not use file extensions File extensions (e.g. .xml) do not add any advantage. If you want to highlight the media type, then you should rely on the media type as communicated through the Content-Type header, which determines how to process the response body’s content.

Hyphens instead of underscores This is mostly preference. But it is suggested to use hyphens instead of underscores as separators. This is because underscores can either get partially obscured or completely hidden in some browsers or screens.

Consistency is key Consistency is key. This will help you navigate and clearly understand what your API endpoint is doing. You should strategically approach it and consider if your naming convention would be clear to someone who’s not familiar with your application. Avoid jargon and abridging, instead use an intuitive naming scheme.

Additional information: Restfulapi.net Nordicapis.com

API Endpoint URLs Each API URL will contain three key elements.

• The Instance URL, for example abz1-def2-efg3.xano.io/

• The API group's canonical identifier, such as api:aBC12z98

• The API name

In some instances, the : character in the API group identifier can cause issues with third party services due to their own non-standard URL validation. To navigate around this, you can replace the : with a - as necessary. No changes need to be made to your APIs; this is always available to you without any intervention on your part.

Error: API name is already in use

You may see this message when either creating new API endpoints, or publishing drafts for existing APIs. This is because the name of the API conflicts with another API endpoint.

Your API endpoint names require uniqueness to make sure that all requests end up in the right place.

For example, if you have the endpoints shown in the screenshot below, you could not add a new GET /service/test because we already have /service/{id}. Xano would have no way of knowing which endpoint to send the request to. We could, however, use /service/special/test, as the name now contains additional nesting to make it unique.

To resolve this message, you can do one of the following:

• Rename the endpoint to something completely unique

• Change the verb of the endpoint (for example, use PATCH instead of POST)

• Add nested parameters to the URL. For example, /service/byId/{id} instead of /service/{id}