In order to use the PEAK Connect API, there are some basics you will need to understand.
*The current version will change over time
PEAK Connect resource URLs all conform to the same general format:
http(s)://<server name>/<version>/<resource name>.<format>
- <server name> is either qa-connect.ascentgl.com for the testing environment or connect.ascentgl.com for the production environment
- <version> determines which version of the resource will be accessed, and is in the format V#. Currently, all resources should be accessed with a version of V1
- <resource name> is the documented name of the resource being accessed
- <format> is one of xml or json
- Content types – XML or JSON
With the exception of the Authenticate resource, which is an HTTP GET method, all PEAK Connect resources are implemented as HTTP POST methods. All of the POST resources can accept either XML or JSON formatted request bodies, and all will provide either XML or JSON formatted response bodies. The format used is determined by 2 means:
- In the HTTP request header, the Accepts and Content-Type header fields can be set to application/xml or application/json
- As part of the resource URL, a suffix to the resource name of either .xml or .json
For example, the URL: http://connect.ascentgl.com/v1/authenticate.xml will return an XML formatted response body, assuming the HTTP header value are set appropriately
Authentication and Access Control
All PEAK Connect endpoints require an access token which allows access to the endpoint resource. These tokens are returned in the response from the Authenticate resource on a successful login. A token is valid for 24 hours from the time it is issued, after which it can no longer be used to authenticate subsequent requests. Once your token has expired, you will need to submit a new request to the Authenticate resources to retrieve a fresh token. When an expired token is sent in a resource request, the service will respond with an HTTP 401 status code.
While a token can be used continuously until the HTTP 401 is returned, you can also compare the expiration fields in the token to determine whether your next request would succeed or not. If the expiration has passed a new Authenticate request can be made to retrieve a fresh token.
HTTP Codes Definition
200 Success: See response body for result payload.
400 Bad input: Required fields missing from input, are malformed or are too numerous.
401 Unauthorized: Authentication failure; invalid credentials.
500 Internal server error: General service failure; retry request.