How do I write a service layer specification?

Question

I'm currently building a frontend prototype for a web application, and soon the backend programmers are going to start building the service layer. They've asked me to write a simple specification of the data formats I want from the various services along with possible parameters etc.

Are there any standard way of writing or structuring such specs? Can anyone give an example?

PS: All the service requests will be done in Javascript asynchronously.

Answer 1

Write an SDD together with the backend crew.

A design document needs to be a stable reference, outlining all parts of the software and how they will work. The document is commanded to give a fairly complete description, while maintaining a high-level view of the software.

• Define the data. Whatever data your application processes ( client and the server ).

• Define the architecture. As you mentioned, you are making HTTP calls from client to server using asynchronic Javascript.

• Define the interfaces. Once you have a common understanding on data and architecture, the interfaces are much easier to put together. Interface descriptions usually describe all functions (with a short description, parameters and return values). If you want an example of RESTful interface description, take a look at enStratus document.

Use lots of pictures and examples to make the document readable. Don't make it too long: K.I.S.S !