Why is the API prefix is useless?

[tomkerkhove]

Current guidelines mention the following:

The API name is a singular concept: https://master-data.contoso.com or https://api.contoso.com/master-data. The API prefix is useless ie api/v1/users/{id}/profile.

Why is that exactly?

[MassimoC]

The sentence is not really clear there are two points here:

1) The api name is singular Don't : https://your-api-name-plural.domain.com/v1/controller Do : https://your-api-name-singular.domain.com/v1/controller

2) The API prefix is useless Don't : https://your-api-name-singular.domain.com/api/v1/controller or https://api.domain.com/api/your-api-name-singular/v1/controller (duplication) or https://data.domain.com/api/your-api-name-singular/v1/controller (what does the "api" word bring to the URL?)

Do : https://your-api-name-singular.domain.com/v1/controller (the api name is in the base, in case u have a common domain per API) or
https://api.domain.com/your-api-name-singular/v1/controller (the api name is explicit)

e.g. https://api.domain.com/master-data/v1/controller https://api.domain.com/hr/v1/controller

[tomkerkhove]

This is the full guidance we have now:

• The API name is a singular concept and the 'api' prefix does not provide an added value
  • Don't - api/v1/users/{id}/profile
  • Do - https://master-data.contoso.com or https://api.contoso.com/master-data

I'll make sure that this is seperated to reflect this.

However, can you provide an example where using api in the uri path is ok, for example this? https://codit.eu/api/v1/users ?

[MassimoC]

I am ok to use API word if really necessary. For example if you have a solution called CDS, that exposes a web interface, a rest api and a soap service, i am ok with the config:

• https:/blabla.here.com/cds/api/v1/users/... (single api dedicated to CDS, the CDS rest api)
• https:/blabla.here.com/cds/web/.... (UI)
• https:/blabla.here.com/cds/ws/cdsservice.svc (classic SOAP naming convention)

Regarding your example, what is the API name? the API name comes always before the version (v1) so in your example, the api name is API, users is the controller. This is fine if you are exposing a single api. But how do you compose your URL when you have more APIs?
https://codit.eu/api/v1/users

[tomkerkhove]

That's a good point, let me send a PR in one of the next days and see what you think.