In order to use these API, you need to provide your customer login details in the header of the request. You can provide these with the userName, password and customerGUID header values.
The username and password are specific to your integration. The CustomerGUID field contains an identifier for the Legend customer that you will be connecting to. Note that your username will need to be enabled for each customer individually.
HTTP Header values as follows:
userName: <somevalue>
password: <somevalue>
customerGuid: <somevalue>
Authentication details are provided upon request.
Note that login details created for the UAT environment are different from those provided for the production ("live") environment. Details created for one environment will not necessarily work for another.
As these authentication details are passed in the header, they will be readable from client-side Javascript applications. If integrating in this way, please use the PublicAPI.
Legend delivers a RESTful interface for its APIs, providing programmatic access to much of the data in the system. It provides predictable URLs for accessing resources, and uses built-in HTTP features to receive commands and return responses. This makes it easy to communicate with from a wide variety of environments, from command-line utilities to gadgets to the browser URL bar itself.
The API accepts JSON or form-encoded content in requests and returns JSON content in all of its responses, including errors.
Sadly, sometimes requests to the API are not successful. Failures can occur for a wide range of reasons. In all cases, the API should return an HTTP Status Code that indicates the nature of the failure (below), with a response body in JSON format containing additional information.
In the event of a server error the response body will contain an error phrase.
| Code | Meaning | Description |
|---|---|---|
| 200 | Success | If data was requested, it will be available in the data field at the top level of the response body. |
| 201 | Success (for object creation) |
Its information is available in the data field at the top level of the response body. The API URL where the object can be retrieved is also returned in the Location header of the response. |
| 400 | Invalid request | This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again. |
| 401 | No authorization | Valid API credentials were not provided with the request, so the API could not associate a user with the request. |
| 403 | Forbidden | The API credentials and request syntax was valid but the server is refusing to complete the request. This can happen if you try to read or write to objects or properties that the user does not have access to. |
| 404 | Not found | Either the request method and path supplied do not specify a known action in the API, or the object specified by the request does not exist. |
| 500 | Server error | There was a problem on Legend's end. |
In the event of an error, the response body will contain an errors field at the top level. This contains an array of at least one error object, described below:
| Example | Description |
|---|---|
| Message: | project: Missing input Message providing more detail about the error that occurred, if available. |
| Phrase: | 6 sad squid snuggle softly 500 errors only. A unique error phrase which can be used when contacting developer support to help identify the exact occurrence of the problem in Asana’s logs. |
Bundles are used to limit the permissions of integrations.
Each endpoint is allocated to one or more bundles. If the integrating software has access to at least one of these bundles then they are able to call the endpoint.