GitScrum's API is based on the REST architecture, allowing you to interact with resources through predictable URLs. The API accepts form-encoded request bodies and returns responses in JSON format, utilizing standard HTTP response codes, authentication, and verbs.
As a project management tool, GitScrum requires you to create a test project in order to test our API.
As new versions of the GitScrum API are released with customized functionality, the API may differ between accounts. The documentation provided is specific to your version of the API and includes your unique test key and data, which are only accessible to you.
https://api.gitscrum.com
The GitScrum API uses API_ID and Project_Key to authenticate requests. You can view and manage your API keys in the Settings section of your GitScrum Project.
In GitScrum API, project keys are unique and tied to a specific project, and API IDs are specific to your account.
Your API keys carry many privileges, so it is crucial to keep them secure. Do not share your API keys in publicly accessible areas such as client-side code, GitHub, and other similar platforms.
All API requests must be made over HTTPS. Calls made over plain HTTP will fail, and API requests without authentication will also fail.
In GitScrum API, we use conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, while codes in the 4xx range indicate errors that occurred due to missing or incorrect information provided (e.g., a required parameter was omitted, an authentication failed, etc.). Codes in the 5xx range indicate an error with GitScrum's servers, which are rare.
Some 4xx errors that could be handled programmatically (e.g., a field is invalid) include an error code that briefly explains the error reported, making it easier for developers to identify and fix the issue.
Attributes
message string
The attribute message is a string that provides a human-readable message with additional details about the error. This message is particularly helpful for resource errors, as it can be displayed to your users, providing more context and helping them to understand the issue at hand.
param string
The attribute param is a string that indicates the specific parameter related to an error if the error is parameter-specific. This can be useful for displaying a message near the correct form field and helping users to quickly identify and resolve any issues with their input.
200 - OK: The request was successful, and the server returned the expected data.
400 - Bad Request: The request was invalid, often due to a missing or incorrect parameter.
401 - Unauthorized: The request was not authorized because the user did not provide a valid API key or authentication token.
402 - Request Failed: The request was valid, but it failed to complete for some reason.
403 - Forbidden: The API key or token provided does not have the required permissions to perform the requested action.
404 - Not Found: The requested resource could not be found.
409 - Conflict: The requested action conflicts with another action that is currently in progress.
429 - Too Many Requests: The user has sent too many requests too quickly. It is recommended to wait and resend the request after an exponential backoff.
500, 502, 503, 504 - Server Errors: Something went wrong on GitScrum's end, and the server was unable to fulfill the request. These errors are rare but can occur due to issues with the server or system maintenance.
In GitScrum API, all top-level API resources support bulk fetches through their list API methods. These list methods follow a common structure and accept at least three parameters: limit, page, and optionally sort.
When you make a request to a list API method, the response will contain a single page of objects from a reverse chronological stream. If you do not specify the page parameter, the first page of the stream will be returned, containing the newest objects. The limit parameter specifies the number of objects to return per page, while the optional sort parameter allows you to specify a field and direction for sorting the objects in the response.
Using these list API methods can be an efficient way to fetch multiple objects at once, reducing the number of requests required and improving the performance of your application.
For example, the snippet you provided shows a JSON response for a paginated result that contains 30 items in total. The count attribute shows that all 30 items are included in the current page, which is the first page (current_page: 1). The per_page attribute specifies that each page should contain a maximum of 15 items. The total_pages attribute shows that there is only 1 page in total for this dataset.
{
"total": 30,
"count": 30,
"per_page": 15,
"current_page": 1,
"total_pages": 1
}At GitScrum, we prioritize maintaining backwards compatibility while continuously improving our API. However, in the event of any backwards-incompatible changes, a new, dated version of the API will be released. Currently, we are at version 2.0.0 of our API.
GET /current-version
{
"version": "2.0.0"
}