OpenLMIS v3 REST API proposed guidelines for POST and PUT

There seems to be a need to clarify guidelines for REST endpoints in regards to POST and PUT and UUIDs for certain resources. Below is what is proposed:

Two types of objects will exist in the system:

1. Ones with a "natural key", i.e. an identifier that is not the UUID. If the natural key is changed, the object's identity is changed. An example is a right and its name–if the name changes, the right has fundamentally changed.
2. Ones without a natural key, so the UUID is the identifier. An example is a role–a role has a name which is unique in the system, but the role's name can be changed, but since its UUID does not change, its identity is still the same.

NOTE: NONE of the endpoints should specify a UUID in the body–all UUIDs should be in the URI.

For resources that have a natural key, here are the following scenarios and what the endpoints should do (using rights as an example):

• POST /rights (natural key in the body) - create a new right this endpoint will not be provided, since the functionality is already in the PUT endpoint
• PUT /rights (natural key in the body) and the right already exists in the system - update the right
• PUT /rights (natural key in the body) and the right does not exist in the system - create a new right

For resources that do not have a natural key, here are the following scenarios and what the endpoints should do (using roles as an example):

• POST /roles - create a new role, generate a new UUID
• PUT /roles/UUID and the role already exists in the system - update the role
• PUT /roles/UUID and the role does not exist in the system - create a new role with the provided UUID

An image of what is described above: