Web api for Bungeni - Githubissues

There is need for a web Application Programming Interface (API) so as to enable 
other applications to interface/integrate with Bungeni data and metadata in a 
formalized way. 

This issue lays out the design considerations for the API and any constraints 
that must be adhered to as well as requirements to be fulfilled.

Design considerations

1.API stack

This defines how the API is invoked and the data representation format(s) used. 
  * A constraint recommendation imposed on the design is that the data and services should be exposed the REST way (http://en.wikipedia.org/wiki/Restful). 
  * Each call to the API will result in a response containing data. The data response format should standardize to either json or xml output.This does not constrain from the service providing both or more data formats. Standard HTTP response codes must also be used.
  * It is recommended to use friendly ids and not system ids for request calls.
  * The API will allow reading and posting of data. This will be determined on a case-by- case review of each service developed for the API.
  * There should be one and only one way to achieve each task.
  * Explicit input/output limitations should be imposed - messages going in or out of the API should be explicitly capped

2.Versioning

The API may change as new features and services are added to Bungeni. To 
prevent breakages occurring for clients already using the API and to cater for 
the addition of new features the API needs to be versioned. 

3.Public/Private api

It is envisaged that the API will be private i.e it is not published for public 
use. However in the event that it is published then an authentication method 
will need to be implemented.

4. Service Contract - 
This will document the different services provided by the API and how to access 
them. This will include:
   1. The different services and their names 
   2. How each service is accessed.
   3. The method signature for each method in a service

   5. A description of each parameter in a method

5. Documentation
The API documentation will cover the following:

  * Definition of all services, methods (actions) and their parameters

  * Sample request / response data formats for each action in the service

  * Documentation of  error scenarios along with Server side status codes
Original issue reported on code.google.com by mng...@gmail.com on 2 Aug 2011 at 1:35
BenoitTalbot / bungeni-portal

Web api for Bungeni #723
