We need to define our requirements for a REST API. What are tools which aid in creating a document which will fully describe the webservice so it can be created by another entity?

1 Answer 1


I am a RESTful web developer (real, "HATEOAS", Level 3 REST) but I have never come across a tool to help me define a service. For general diagramming purposes however, I do like OmniGraffle.

To be honest, I think a text editor, a knowledge of the domain and of the recipient's level of vocabulary and understanding, are all you really need.

Are you wanting to specify every resource and how it relates to every other resource? How low down into the details are you trying to go?

  • The level we intended to describe is about this "Our search request will look like this, the fields in our imput data will need to be interpreted like this (handling of precedence etc.), and we would like to get these fields filled, were each fields should behave like this (e.g is counting started at 0, what happens if there are no results etc.). Hope this comes across right, its my first try on formulating such software requirements. Jul 15, 2013 at 8:27
  • The best requirement specification is a comprehensive test suite. However that may take longer to write than you are willing to give. I suggest you look through stackoverflow.com/questions/2001899/… as much is covered that that would be relevant. You target audience is a human, so human-readable descriptions will still be important. Jul 15, 2013 at 8:35

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.