Implementation detail vs. specification and examples

1

A given resource must have a unique type and id combination. We are designing to a UUID for id, however, I’m starting to see that this would not be a human manageable id in a GET, e.g., GET /resources/65348dfe-d875-4146-99c1-e443c0f1b955 HTTP/1.1.

The resource response would have a more human readable resourceId in its attributes, e.g., data.attributes.resourceId, i.e., this might be a legacy sequence number, 12345.

Maybe I’m over thinking this, but this feels like an implementation detail for me to solve, i.e., if my resource endpoint looks like GET /resources/12345 HTTP/1.1 it’s expected of me to perform the correct fetching on the repository.

This may seem pretty basic, but with type and id being top level, the examples do suggest that a type of articles and an id of 1 results in a resource endpoint of GET /articles/1 HTTP/1.1. I would need specific implementation details to override that assumption.

Is there an OpenAPI example out there I might review?

2

I find it helpful to keep these points in mind:

  • The specification does not say anything about how URLs have to be structured; all URLs are generated on the service side and not in the client. (This is a good idea in any distributed applications using URLs to provide access.)

  • While the examples in the specification are intended for human consumption (the developer reading the spec), they might not be realistic for an actual application.

So, perhaps “human consumption” isn’t a goal.

-Fred

1 Like
3

Thanks @fdrake for the response! Sometimes one just needs some affirmation that their guess at the intent is not a gross misunderstanding.