In my last post I discussed the need to carefully construct your resource and message representations in order to increase the flexibility of your design over time. Great care needs to be taken to avoid many of the pitfalls which can befall your design with insufficient attention. A considerable portion of your time as a designer of a hypermedia web api should be spent designing your representations. This post may then come as a small relief as I would like to talk about removing an entire concern from your API designer mind to free up time for the previous discussion; the URI pattern.
For the most part the guidelines previous to this one could largely be followed in a crud or hypermedia web api and you could expect improved results regardless. This trend ends now, and depending on your attachment to the tools or strategies I’m about to reference, this might upset you. Immediately stop spending any design energy on your URI pattern philosophy, rotation, choice, or strategy as you simply won’t need it.
The documentation and standardization around a hierarchical URI pattern generally wastes an inordinate amount of designer and developer time before some semblance of a workable design reaches the hands of a capable developer. In order to help speed up this process of wasting time, many solutions like OAS (Swagger), Apiary.io, RAML, etc.. have been created to cut out chunks of effort to disprove a design. This statement isn’t to be taken out of the appropriate context, as previously stated hypermedia web api’s are not right for every situation. There are many viable situations where the solutions they offer are the correct tool for the job. However, scaling those solutions to a large domain size with limited or no control over consumer code, and desiring high utilization endurance over time, it becomes an exceptionally difficult task to accomplish. I would argue the longer you desire the API to run unmodified, the closer to effectively impossible the task becomes, and the point where this occurred wouldn’t be anywhere near as far in the future as you might believe.
Overloading the URI structure to contain semantic information places a tremendous amount of pressure on the designer to allow enough gap for future growth and needs within the hierarchy. It also places a huge burden on the consumer of the service to know a lot of information about your service before being able to fully utilize it. Kin Lane (“the api evangelist”) on the recent Api Academy podcast described this as human targeted documentation and tooling. Meaning that while tooling can help set up some of the boilerplate code, the responsibility for tying things together is left for the human developer.
When utilizing a hypermedia web api which matches the preceding four guidelines, the URI pattern for resources is entirely irrelevant as the actual URIs are completely opaque to a consumer of the API. With the root resource representation name of ‘user’, and assuming complete home document, and vocabulary definitions, the actual URI for the resource is meaningless.
With the same conditions stated above, the user resource being under ‘/uusdfskd231232/’ and the hypermedia client would have no difficulty whatsoever discovering the resource, nor surfacing the context to a human consumer. The same is obviously not true of the human integration developer, whom must consult some external documentation to identify the change. As a consequence, moving the resource to another URI would simply be a matter of making some small modifications to the profile, and this would be entirely unrecognized by the clients. It is important to not, I do not advocate obscuring the URLs of the resource unless your design absolutely calls for it, where possible an intelligible and human friendly format should be used but it should not become an obstacle of any note.
By utilizing the representations painstakingly created following the previous guideline, your service doesn’t need to worry about creating the perfect hierarchy structure for your API, it just doesn’t.