Domain Guidance

[kinlane]

Do we want to provide domain guidance for implementations? Recommend folks do api.example.com, or example.com/api.

Consider offering portal advice too, like developer.example.com.

[timgdavies]

As soft guidance, but not requirements perhaps.

I think more important, and I don't think it's picked up in #8 would be guidance on versioning within the API urls. E.g. should URLs all start /v1/services etc.

[klambacher]

I think this is an unnecessary level of implementation direction and should be beyond the purview of the spec (even as suggestion). The implementation should be able to begin the API nested under an arbitrary domain and route, IMO. I don't believe that standardizing this adds benefit, so I see it is an unnecessary complexity.

The recommendation to nest versioning in a specific place in the routing path is a more practical recommendation I think. This allows those with the means to simultaneously support multiple versions, explicitness in transitions between versions, and hopefully will allow for gentle transitions. In this case, I think the version number should be a standard part of the route path so that this is expected and predicable. Do you see any advantage of including a /latest/ option?

[kinlane]

Definitely agree it shouldn't be anything enforced, just soft guidance--some operators may not have any control at this level.

However I do find guidance, and recommendations regarding best practices help with stability, and reliability of implementations. When buried in a folder somewhere, things get lost. When at subdomain it tends to get first class, or at least more attention.

Thanks for the versioning thoughts...agreed! Linking to that conversation.

[kinlane]

Oh and your latest option....would love more clarification -- interesting. Do you mean latest version of API? or latest updates to data (maybe linking to metadata conversation)?

[timgdavies]

I believe a /latest/ path would point to the latest version of an API.

I would think this should be avoided, as the point of a versioned API path is to avoid applications accidentally being hit by breaking changes.

Given using semantic versioning, a 1.1 of an api should be backwards compatible, I would suggest that versioning in the URL only needs to accommodate the MAJOR version:

I.e. /v1/ will point to the latest MINOR release from the 1.x series so that a change of path is only needed for a backwards incompatible /v2/ release

[kinlane]

I'm moving @timgdavies comment to the versioning discussion and closing this. My recommendations is no guidance at the domain level for now to not muddy the conversation.