API Guide ========= Overview -------- KForge is not only available in a web browser, but also via its Application Programming Interface (API). The KForge API follows the RESTful (Representational State Transfer) style. Resource locators are separated both from the methods that are supported by the resources, and from the data formats and status codes used by the methods. This document describes the resource locators, data formats, and status codes which comprise the KForge API. Locators -------- The locator for a given resource can be formed by appending the relative path for that resource to the API locator. :: Resource Locator = API Locator + Resource Path The API locator for a given site is constructed by appending 'api/' to the site's base locator. :: API Locator = Site Base Locator + 'api/' For example, if the site's base locator is 'http://projects.appropriatesoftware.org/' then the API locator will be: :: http://projects.appropriatesoftware.org/api/ If in doubt, there is a link to the API from the `API key page `_ within KForge's Web UI. Resources --------- The relative paths for each resource are listed in the table below. +--------------------------------+-------------------------------------------------------------------+ | Resource | API Path | +================================+===================================================================+ | Person Register | ``/people`` | +--------------------------------+-------------------------------------------------------------------+ | Person Entity | ``/people/PERSON-NAME`` | +--------------------------------+-------------------------------------------------------------------+ | Project Register | ``/projects`` | +--------------------------------+-------------------------------------------------------------------+ | Project Entity | ``/projects/PROJECT-NAME`` | +--------------------------------+-------------------------------------------------------------------+ | Member Register | ``/projects/PROJECT-NAME/members`` | +--------------------------------+-------------------------------------------------------------------+ | Member Entity | ``/projects/PROJECT-NAME/members/PERSON-NAME`` | +--------------------------------+-------------------------------------------------------------------+ | Service Register | ``/projects/PROJECT-NAME/services`` | +--------------------------------+-------------------------------------------------------------------+ | Service Entity | ``/projects/PROJECT-NAME/services/SERVICE-NAME`` | +--------------------------------+-------------------------------------------------------------------+ Todo: Add pending members, tickets, plugins, licenses, roles, actions, protection objects, permissions, grants. Methods ------- Standard HTTP methods are used to interact with the resources. GETing a register resource will return a list of entity locators. POSTing to a register resource will create a new entity. The locator for the new entity will be returned in the 'Location' header of the response. GETing an entity resource will return the attributes of that entity. PUTing (or POSTing) data to an entity resource will update the entity. Please note, PUT operations may instead use the POST method. +-------------------------------+--------+------------------+-------------------+ | Resource | Method | Request | Response | +===============================+========+==================+===================+ | Person Register | GET | | Person-List | +-------------------------------+--------+------------------+-------------------+ | Person Register | POST | Person | | +-------------------------------+--------+------------------+-------------------+ | Person Entity | GET | | Person | +-------------------------------+--------+------------------+-------------------+ | Person Entity | PUT | Person | | +-------------------------------+--------+------------------+-------------------+ | Project Register | GET | | Project-List | +-------------------------------+--------+------------------+-------------------+ | Project Register | POST | Project | | +-------------------------------+--------+------------------+-------------------+ | Project Entity | GET | | Project | +-------------------------------+--------+------------------+-------------------+ | Project Entity | PUT | Project | | +-------------------------------+--------+------------------+-------------------+ | Service Register | GET | | Service-List | +-------------------------------+--------+------------------+-------------------+ | Service Register | POST | Service | | +-------------------------------+--------+------------------+-------------------+ | Service Entity | GET | | Service | +-------------------------------+--------+------------------+-------------------+ | Service Entity | PUT | Service | | +-------------------------------+--------+------------------+-------------------+ | Member Register | GET | | Member-List | +-------------------------------+--------+------------------+-------------------+ | Member Register | POST | Member | | +-------------------------------+--------+------------------+-------------------+ | Member Entity | GET | | Member | +-------------------------------+--------+------------------+-------------------+ | Member Entity | PUT | Member | | +-------------------------------+--------+------------------+-------------------+ Todo: Method for deleting entities. Formats ------- +--------------------+------------------------------------------------------------+ | Name | Format | +====================+============================================================+ | Person-List | |format-person-register| | +--------------------+------------------------------------------------------------+ | Person | |format-person-entity| | +--------------------+------------------------------------------------------------+ | Project-List | |format-project-register| | +--------------------+------------------------------------------------------------+ | Project | |format-project-entity| | +--------------------+------------------------------------------------------------+ | Service-List | |format-service-register| | +--------------------+------------------------------------------------------------+ | Service | |format-service-entity| | +--------------------+------------------------------------------------------------+ | Member-List | |format-member-register| | +--------------------+------------------------------------------------------------+ | Member | |format-member-entity| | +--------------------+------------------------------------------------------------+ .. |format-person-register| replace:: [URL, URL, URL, ...] .. |format-person-entity| replace:: {'name': String, 'fullname': String, 'password': String, 'emailAddresses': URL, 'memberships': URL, 'role': URL, 'dateCreated': DateTime, 'lastModified': DateTime} .. |format-project-register| replace:: [URL, URL, URL, ...] .. |format-project-entity| replace:: {'name': String, 'title': String, 'description': String, 'members': URL, 'services': URL, 'licenses': [URL, URL, URl, ... ], 'isHidden': String, 'dateCreated': DateTime, 'lastModified': DateTime} .. |format-service-register| replace:: [URL, URL, URL, ...] .. |format-service-entity| replace:: {'name': String, 'plugin': URL, 'project': URL, 'status': String, 'dateCreated': DateTime, 'lastModified': DateTime} .. |format-member-register| replace:: [URL, URL, URL, ...] .. |format-member-entity| replace:: {'person': URL, 'project': URL, 'role': URL, 'dateCreated': DateTime, 'lastModified': DateTime} Status Codes ------------ Standard HTTP status codes are used to signal method outcomes. ===== ===== Code Name ===== ===== 200 OK 301 Moved Permanently 400 Bad Request 403 Not Authorized 404 Not Found 409 Conflict (e.g. name already exists) 500 Service Error ===== =====