-
Notifications
You must be signed in to change notification settings - Fork 3
The Web API is a new REST based interface to key parts of the TeamHaven Server business layer. It is available under the /api URL of a TeamHaven server, and it is available via HTTPS at https://www.teamhaven.com/api.
- Authorization
- Content-Type header
- Status Codes
- HTTP Redirects
- User-Agent header
- API versioning
- General recommendations
Authorisation is done using the standard HTTP Authorization header. There are two authorisation schemes, both of which use the same basic format for a set of TeamHaven credentials:
username/account:password
Typically, authorisation should be performed with HTTP Basic authorisation, using Base64 encoded TeamHaven credentials.
Authorization: Basic c3RvbnkvdGVzdDp0ZXJyaWVy
However, for debugging purposes, it is also possible to provide unencoded credentials using "TeamHaven" as the authentication scheme name rather than "Basic".
Authorization: TeamHaven username/account:password
In addition, a standard TeamHaven authentication cookie can also be used, so that if web pages on the TeamHaven website wish to use the WebAPI, they may do so without having to provide any authorisation information, as their requests will already contain the required cookie. This means it is possible to log into the TeamHaven website and review the output of any GET requests via a web browser, provided it can request and display XML or JSON output.
Request content must be UTF-8 encoded and presented as text/json or application/json.
Content-Type: application/json; charset=UTF-8
Any status code in the range 200 - 299 indicates that the request was successful. The actual status code value will vary according to the specific API being used.
Resource has permanently moved to a new location. This old location is being maintained for backwards compatibility only and may be removed in the future. Update your code to reflect the new location.
Resource has temporarily been moved to a different location, resubmit your request to the new location.
Something was wrong with your request. Check the Message property of the response for more information about what was wrong.
Make sure that your request is valid - check the headers and the content.
Make sure you have provided a valid Authorization header. Make sure that the Username, Password and Account are correct.
The credentials contained in the Authorization header to not permit access to the requested resource.
The requested resource could not be found. Make sure the URL is correct, and if it is, make sure that the ID of the resource you are trying to access is also correct. Eg:
/api/call/1234 - This is incorrect because the API URL is /api/calls (not /api/call).
/api/calls/4567 - This might return 404 because Call ID 4567 does not exist.
The resource you are trying to access has been deprecated and subsequently removed from the API. Update your application to use the latest version of the API.
The user agent's IP address has made too many requests and is now being throttled. The Retry-After header will indicate how long the agent must wait before new requests will be serviced. Make no more requests from this IP address until then. Not currently implemented
Status codes in the range 500 - 599 indicate that an error occurred on the server while processing the request. Contact support@teamhaven.com for assistance and be sure to include the full HTTP request you are making, including the full URL, the HTTP verb, the Authorization and Accept headers, and the body content.
The API uses HTTP redirection where appropriate. Clients should assume that any request may result in a redirection. Receiving an HTTP redirection is not an error and clients should follow that redirect. Redirect responses will have a Location header field which contains the URI of the resource to which the client should repeat the requests.
The API expects that the User-Agent header conforms to the following syntax:
User-Agent: app=your application name; email=your contact email address
Optionally you may also include version information:
User-Agent: app=TeamHaven Mobile for Android; v=2.1.3241; email=support@teamhaven.com
Other User-Agent values will be tolerated for minor usage, but sustained usage will result in a 400 - Bad Request response.
The API uses the Accept header to allow applications to identify a version-specific format of a resource:
Accept: application/vnd.teamhaven+json; v=1 - This requests version 1 of a resource representation to be returned in JSON encoding.
In cases where the Accept header is not specified, or a generic MIME type such as application/json is requested, then the API will always use the most recent version.
Other values of the Accept header may result in a 406 - Not Acceptable response.
Wherever possible, TeamHaven will use the same URL for the same resource between all API versions. For instance, API v1 and API v2 will both use /api/calls/:id to access a Call. However, v2 of the API may return a different representation of the Call - perhaps there will be additional fields, perhaps the structure will have changed. To select between the two different representations, use the Accept header described above.
In situations where a part of the API has been removed, the API will return a 410 - Gone response, indicating that the resource no longer exists.
If the API has been moved to a different URL, then the server will respond with 301 - Moved Permanently and the Location header of the response will indicate the new URL. If your application starts receiving 301 responses, then please review the relevant parts of the API documentation and update your application accordingly.
- Always use HTTPS when connecting to the API to prevent your credentials from being intercepted by packet-sniffers.
- Be prepared for the API to return 301 and 302 redirect responses and resubmit your request to the new location. Perhaps flag 301 responses to a developer so they know that they are aware the application is using deprecated URLs.
- Never assume that your API call will succeed - always check the response status code.