Endpoint URL Name

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