Very few API methods actually accept the DELETE method, and POST can be used for creating or updating. PUT will only create new resources, and will return an error code otherwise.

Authentication

Most of the methods in the API require authentication, and will respond with a 401 (Unauthorized) if credentials are not supplied. You can supply credentials using any HTTP Basic Auth approach. Most HTTP client libraries (for, e.g., PHP, .NET, Java) include a handy method to specify a username and password. You can also specify it in the URL itself, for example:

http://username:password@<gforge url>/api/...

If you receive a 401 (Unauthorized) response after providing credentials, it means that your account is not allowed to perform the specified operation.

Requests

In general, making a request is just like using a web browser: Specify what you're looking for in the URL, or submit new information in a FORM. All of the entity types and field names are specified below, and there are examples at the end of this page to get you started.

To retrieve a specific resource by its unique identifier (also called its ID throughout this guide), use a GET request with the following format:

http://<gforge url>/api/entity/ID

To search for resources using filter criteria, use a GET request with the following format:

http://<gforge url>/api/entity?[fieldname=x][&otherfield=y]...[&page=n][&start=m][&format=fmt][&rel=list]

where:

• fieldname, otherfield are the name(s) of fields on the entity being searched.
• pagesize is the maximum number of resources to return, regardless of the number that match the criteria. Default is 25 resources.
• firstpage is the one-based index of the page number to be returned, using the specified page size. Default is always the first page.
• format identifies the desired formatting for the response document. Valid values are csv, xml and json. Default is json, which is also used if an invalid (or empty) choice is provided.
• rel is a comma-separated list of related entities to be returned as part of the resource. Valid values vary by the main entity being searched, see below for details.

Clients can also specify the format using the standard "Accept" HTTP header, or by including the desired format in the URL:

http://<gforge url>/api/entity/[criteria clause]/format

where format is one of the choices identified for the format parameter above and [criteria clause] is any set of allowed parameters in the previous example.

If format is specified in multiple locations, the path element is preferred, followed by the explicit GET parameter, then the HTTP header. If no (valid) format is specified, JSON is the default.

To update a specific resource, include its ID in the request URL (just like the GET)...

http://<gforge url>/api/entity/ID

...and then specify one or more field/value pairs in a standard FORM POST body (what are my options?). Be sure you only include settable fields in the body. The system will return a 400 (Bad Request) status if you try to set a read-only field - see the entities definitions below for specifics.

To create a new resource, specify only the entity type (no ID exists yet):

http://<gforge url>/api/entity/

You can submit the same body as noted above for updates, using either the POST or (more appropriately) the PUT HTTP method.

Responses

The API server will respond with standard HTTP status codes, depending on the method, entity, and data you specified, and the success or failure of the request.

For GET requests:

• 200 (OK): Your request worked. The document returned is the information you asked for.
• 400 (Bad Request): Your request was not processed because your request was not valid. Check the document returned for more information.
• 401 (Unauthorized): You're not allowed. You need to provide a username and password to see the results of the request. If you specified a username and password, it was not valid, or did not have sufficient privileges.
• 404 (Not Found): Your request worked, but returned no results. Usually the result of a request for a specific entity by ID. A search with no results will still return 200 (OK).
• 500 (Server Error): Your request was not processed because an internal error occurred. Check the document returned for more information.

For other request types, the GET responses noted above apply, except for 200:

• For POST requests, the Location header will contain the URL to retrieve the updated resource. The document will contain HTML with a link to the same resource identified in the Location header.
• For PUT requests, 201 (Created) will be returned. The Location header will contain the URL to retrieve the new resource. The document will contain HTML with a link to the same resource identified in the Location header.
• For DELETE requests, 204 (No Content) will be returned. No body will be returned.

Backgroundable methods

Some methods require many operations and are too resource expensive for large amount of items in the same request (An example would be Mass Update on 50 tracker items). For these cases the API server shows a 'backgrounding' attribute in the method description, marking it as Backgroundable.
Backgroundable methods can decide to handle the request online or as a server background process, it will return different results for each case. This is a workflow example:.

1. The method calculates the total number of items to be handled. For this example let's call it NN.
2. If NN is lower than the predefined system setting the request is processed online and the request is completed.
3. If NN is equal or higher than the limit the request data is stored in the database as a new Background job, the job id is returned and the request is completed.
4. The user can monitor the job progress using the received jobId and the Poll service. See the Poll resource definition for details.

Every backgroundable method will provide details about the limit setting used and the format of the results on each case.

Configuration

Classes, functions and variables that depend on configuration variables (from the ConfigurationService) should be documented in a comment block, using one or more @config attributes, along with the config entry name, description and default value, for each config entry that is referenced.

GForge Next Site Config Opens in a new tab. Requires Site Admin privilege in GForge Next.

Resources

The API is divided into logical sections of functionality called plugins, each of which offers one or more resource types. Plugins may be enabled or disabled for each GForge site, user or project (depending on the type of plugin), so not all resources will be available for every project