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.
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:
If you receive a 401 (Unauthorized) response after providing credentials, it means that your account is not allowed to perform the specified operation.
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:
To search for resources using filter criteria, use a GET request with the following format:
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)...
...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):
You can submit the same body as noted above for updates, using either the POST or (more appropriately) the PUT HTTP method.
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:
For other request types, the GET responses noted above apply, except for 200:
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:.
Every backgroundable method will provide details about the limit setting used and the format of the results on each case.
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.
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