Re-design the registry API

[johannesduesing]

Describe the problem
The current design of the HTTP API of the registry is not at all REST-like. Instead of using query parameters, we should really be using the URLs to encode ids of instances. Requests with the HTTP method POST should use the request-body to transmit the parameters, not the query parameters.
The way the API is designed right now, it is not at all intuitive to use.

Describe the solution you would like
Please re-design the API in a RESTful way. A good example for API design is the swagger petstore example. This contains the following tasks:

• Create a new swagger API specification file
• Implement the newly designed API (change the Server.scala accordingly)
• Change all dependencies (all delphi components) accordingly

[johannesduesing]

@24santoshr thanks for your submission of the API specification. I will try to give you some feedback for all the API commands below:

• I agree to your design of register and deregister, that's exactly how i thought it should look like 👍
• For the GET methods of instances, i think you mixed something up there. There is one endpoint for retrieving an instance match (in your version called instances/componentType which seems pretty confusing to me) which must have two query parameters, namely Id for the caller-id, and ComponentType for the requested type of instance. I thought it would be something like GET instances/{id}/matchingInstance with query parameter ComponentType.
• For getting a single instance with a specified id, something like GET instances/{id} would make sense
• For getting all instances of a specified type, you have proposed the GET /instances endpoint, which is fine. But in your specification there is a query parameter Id, which does not make sense to me in that context. Also i would suggest to make the query parameter ComponentType here optional, so that you can get all instances of all types by just omitting the parameter
• I like your way of defining the instances/count endpoint. Maybe you can also consider to make the parameter ComponentType optional to count all instances of every type.
• Your endpoint for posting a matching result is missing a required parameter, namely the CallerId. I thought of it like this: POST instances/{matchedInstanceId}/matchingResult and, since it is a POST request, the two other parameters CallerId and MatchingSuccessful should go into the body, not the query
• I did not find the endpoints /eventList, /linksFrom, /linksTo, /network and /addLabel in your specification, did you miss them? I thought of something like GET instances/{id}/eventList, GET instances/{id}/linksFrom (same for linksTo), GET instances/network and POST instances/{id}/label with body parameter Label.
• I found the syntax of your deployment-endpoint pretty confusing. I think the basic REST syntax like POST /instances with body-parameters (because its a POST request) ComponentType and InstanceName would be better.
• For all your docker operations: Please move the id into the path, as discussed in our last meeting. For example your endpoint POST instances/reportStart with query parameter Id should actually be something linke this POST instances/{id}/reportStart. Same goes for start/stop/delete/pause/resume/reportFailure.
• I did not find the reportStop and assignInstance endpoints in your specification. reportStop should be handled the same as the other docker operations, and for assignInstance i thought of something like POST instances/{id}/assignInstance with body-parameter AssignedInstanceId.

I'm sorry for the long comment, i just wrote all that came to my mind while reviewing the file. I hope this is enough input for you to create a new iteration of the specification before implementing it.

[24santoshr]

Thanks for the inputs. Will start doing the changes and give an update soon 👍

[24santoshr]

Hey @johannesduesing , could you please review the API specification now and let me know for any changes required.

For POST instances/{matchedInstanceId}/matchingResult, I tried to define both CallerId and MatchingSuccessful as body parameters but apparently swagger does not allow multiple body parameters. Do you want me to create a new separate definitions for matchingResult containing callerId and Matching successful as properties in the swagger file?

[johannesduesing]

@24santoshr thanks for your work. I looked through the specification, it looks about right to me.
There have been some issues with copy/paste bugs, inconsistent spelling and parameters being query-params instead of body-params, but i fixed that myself in a short commit. Please have a look through my changes and tell me if you agree with them.

I will discuss this proposed API specification with the Delphi Management group on Thursday, if they agree with it you can start implementing the changes 👍

[johannesduesing]

@24santoshr please go ahead and start with the implementation. Ideally, this should only affect the Server.scala file, but maybe some of the changes require you to touch other parts of the application (Making the ComponenType optional for example will require you to change the RequestHandler).
Also the HttpTests need to be updated accordingly.

[24santoshr]

Referring #90