Problem: HTTP REST API is inconsistent, under-documented, divorced from client code, and lacking needed endpoints

[jrwdunham]

1. Inconsistent. The endpoints are defined via code in locations/api/urls.py and locations/api/resources.py and it is not very clear from looking at that code what is the pattern of HTTP method and path pattern (e.g., GET /locations/, GET /locations/<UUID>/, etc.) that each resource exposes and why. The pattern of endpoints for making CRUD requests against SS resources should be consistent so that consumers of the API can learn it and use it more easily.

2. Under-documented. The SS's HTTP (REST) API is documented on the Archivematica wiki at https://wiki.archivematica.org/Storage_Service_API. However, because the documentation is completely separate from the code that defines the API, it is an added burden to keep both in the same updated state.

3. Divorced from client code. There are several clients of the SS HTTP API. Archivematica has its own Python module for making calls against the SS API. The same is true for the Archivematica Automation Tools, the Archivematica Automated User Acceptance Tests (AMAUAT), and probably also for other tools not under Artefactual's stewardship. Whenever the SS API changes, the clients in all of these separate locations must all be individually changed to match, which is another burden that costs time and money. It would be great if client code could be generated from the server-defined API.

4. Needed endpoints are lacking. If a user wants to, say, search over File models in the database or create new Location models via the API, then these new endpoints must be created on an ad hoc basis. We cannot anticipate all uses that users may want to put our APIs to. Therefore, we should expose standard CRUD endpoints on the resources that should be under user control, instead of waiting to respond to user requests or (worse) encouraging users to stop using the tool because the API is lacking.

Any work on the Storage Service that resolves this issue should be transferable to Archivematica and should help to address related issues, such as artefactual/archivematica#1113.