When I write a soap service it is very easy to provide my clients a contract of what to expect from my service. How to call it, return types etc. This contract my clients can generated them self when they know the URL of my service and it is described in WSDL language.
What are best practices come rest ? For instance my newly created rest service has just 2 methods:
1) A ping service that needs NO request payload and just returns a plain string "OK" in the response body if it is up an running. That GET request from a browser looks like this http://localhost:8080/rest/ping). There are no request parameters nor a request body.
2) The second one is a create user service that needs a User object as input with a first name and last name as mandatory fields. It returns the newly created user back to client in the response body represented in json.
That POST request from postman can look like this: http://localhost:8080/weather/rest/weather/. It has no request parameters, but includes a request body, i.e "{"firstname":"john", "lastname":"smith"}". The string is represented as json in this example. (does it need to be ? Are there better way to send "objects" to my service ?). Both these are mandatory and would like to tell my clients that somehow.
The response is the user sent back to the client and also includes a email address fields which my service has generated, in addition to the first name and last name provided. It looks like this: {"firstname":"john", "lastname":"smith", "email":"john.smith@example.org"} and is in the response body. Again, are there better ways to return "objects" back to clients than representing them as json ?
So tl;dr: What's the best way to "expose" these services to my client without telling with words how to use it. AFAIK there are no WSDL contract or similar that are usually used when working with rest.
Thanks for your time. And hopefully this is a not a pure duplicate of some similar question.
