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	[URL, URL, URL, ...]
Person	{‘name’: String, ‘fullname’: String, ‘password’: String, ‘emailAddresses’: URL, ‘memberships’: URL, ‘role’: URL, ‘dateCreated’: DateTime, ‘lastModified’: DateTime}
Project-List	[URL, URL, URL, ...]
Project	{‘name’: String, ‘title’: String, ‘description’: String, ‘members’: URL, ‘services’: URL, ‘licenses’: [URL, URL, URl, ... ], ‘isHidden’: String, ‘dateCreated’: DateTime, ‘lastModified’: DateTime}
Service-List	[URL, URL, URL, ...]
Service	{‘name’: String, ‘plugin’: URL, ‘project’: URL, ‘status’: String, ‘dateCreated’: DateTime, ‘lastModified’: DateTime}
Member-List	[URL, URL, URL, ...]
Member	{‘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