There are probably some defects and inconsistencies in Guvnor REST API. I am not sure about all of them so we should discuss what is the expected behavior.

Organizational units:

1. description field is not propagated when calling POST /organizationalunits to create or POST /organizationalunits/orgUnitName to update organizational unit although it is always present (empty) in a response.
2. When you try to update the name of organizational unit by calling POST /organizationalunits/orgUnitName, you will get IllegalArgumentException: OrganizationalUnit orgUnitNewName not found. This is probably caused by a wrong query which uses new organization unit name instead of the old one specified in the path to find the existing organizational unit. Since in GUI it is possible to update everything but the name, I assume it is not allowed to change it and such request should return bad request with a short explanation.
3. When you create a new organizational unit by calling POST /organizationalunits and specify a list of repositories which already belong to other organizational unit, they will be in both of them after this call. Is it supposed be like this? Can one repository belong to multiple organizational unit? It is not possible to do something like that using GUI.
4. When you try to add a repository to an organizational unit which it already belongs to by calling POST /organizationalunits/organizationalUnitName/repositories/repositoryName, you will get SUCCESS in the response. It this correct behavior? I am not sure what is expected here. Should it not return BAD REQUEST instead?
5. When you try to remove a repository from an organizational unit which it does not belong to by calling DELETE /organizationalunits/organizationalUnitName/repositories/repositoryName, you will get SUCCESS. Should it not return NOT FOUND?
6. DELETE /organizationalunits/organizationalUnitName behavior should be unified with DELETE /repositories/repositoryName and DELETE /repositories/repositoryName/projects/projectName and all three operations should either return SUCCESS or NOT FOUND when you try to delete not existing entity.

Repositories:

1. When using POST /repositories to create a new repository, the description field is not saved.
2. When you try to clone not existing repository, you will get SERVER ERROR. If possible, it would be nice to have BAD REQUEST response with the explanation instead.
3. There are three required parameters when creating a new repository - repository name, organizational unit name, and request type. If you skip one of those, you will get different error codes in a response based on which parameter was not provided. The behavior here should be unified and you should always get BAD REQUEST together with some explanation what is required.
4. The behavior of DELETE /repositories/repositoryName needs to be unified with other entities.
5. There are some unused fields in RepositoryResponse when you call GET /repositories/repositoryName. Is it really necessary to have username and password there? And what about requestType? It is always null in the response. And gitUrl is always returned like "git://repositoryName". Should it not be either null or with the original repository URL which it was cloned from? Or should not it be the local URL from which this repository can be cloned now? That would make more sense. We should think about the usage of all of these parameters, fix the ones that are still valid and remove the rest.
6. There is no way to update the repository. It is probably intended but I just want to make sure it is supposed to be this way.

Projects:

1. It is not possible to get a single project. Even though there is not much information about a project, it would be useful to have such method. Imagine the situation when you want to check if some project exists and create or delete it based on the result. Right now you have to get a list of all projects and check if it is there. It is not very efficient way of getting this information.
2. POST /repositories/repositoryName/projects/ with empty project name returns SERVER ERROR instead of BAD REQUEST.
3. There is no way to update a project using REST API even though it is possible using GUI.
4. When you try to delete not existing project using DELETE /repositories/repositoryName/projects/projectName, you will get FAIL response status with message Project projectName could not be deleted: null. This should be unified with organizational unit and repository calls and return either SUCCESS or NOT FOUND.
5. It is not possible to call POST /repositories/repositoryName/projects/projectName/maven/install or POST /repositories/repositoryName/projects/projectName/maven/deploy twice in a row with the same project. You will get Project's GAV already exists.