APAP template and agreement identifier improvements

[niallroche]

Having the name property of the template being used as the identifier has some potential issues regarding the lack of restrictions in the name as it is a string. For example, having a string with no restrictions can cause an issue in using this name as a reliable storage identifier in approaches such as AWS S3 due to object name restrictions. Other storage mechanisms may have similar constraints or max length. There is also the issue of global uniqueness and potential for name clashes. There are likely some trade offs and best practices in REST for client naming versus server naming using something like an auto-increment or a GUID/UUID.

[niallroche]

Possible Pattern for resource creation responses:

• HTTP Method: POST to the collection endpoint (e.g., POST /agreements or POST /templates).
• HTTP Status Code: 201 Created upon successful creation. This clearly indicates that a new resource has been successfully created.
• Response Headers:
• Location: Set the Location header to the URI of the newly created resource (e.g., Location: /agreements/{newlyCreatedId}). This helps the client easily find the full resource representation. Consider including version in the url path too.
• Response Body: Include at least the newly generated ID in the response payload. This might look like:

{
  "id": "09d236f0-4ace-4b1e-a8b5-9cfcb49f32bd",
  "version": "maybe add the version here if that has changed via a PUT request",
  ...
}