RESTful APIs
There are a number of API methods available to interact with Trakr. We are continuing to develop the API to make it as flexible as possible to fit all needs.
Access the API
In order to access the API, you will need to generate an API key which you can find on your user account page. API endpoints are available through various request methods below.
API endpoints
When you access each of the API methods, please make sure you include your API key (x-api-key) in the request header in order to authenticate yourself. The response for the API will be a JSON message that looks like:
{"status": "status_message", "result": "message or result set"}
There is only two status message:
- success
- error
If the API returns data, it will be encapsulated in the “result” element.
Retrieve the status of a screenshot collection or comparison
This API call will provide the status of a screenshot collection or comparison and let the caller know if the task is complete (or in progress) and in case of the comparison, the amount of difference found.
Endpoint: /api/v1/status/[id]
Request method: GET
Method arguments:
- id (required) – the numeric id of the screenshot collection or comparison
Example: curl --header 'x-api-key: cf160643934c3628fc736f7f6f124f35' --request GET https://app.trakr.tech/api/v1/status/1234
Get all comparisons for a project
This API call will retrieve all of the comparisons for a project and some high-level information
Endpoint: /api/v1/project/[id]/get_comparisons
Request method: GET/POST
Method arguments:
- id (required) – the numeric id of the project.
Example: curl --header 'x-api-key: cf160643934c3628fc736f7f6f124f35' --request GET https://app.trakr.tech/api/v1/project/41/get_comparisons
Example result {"status":"success","result":[{"id":112,"score":100,"progress":{"done":"1","total":"1"}},{"id":114,"score":100,"progress":{"done":"1","total":"1"}},{"id":117,"score":100,"progress":{"done":"1","total":"1"}}]}
The result set is a nested JSON with the following attributes:
- id – the comparison id
- score – relative score (based on 100) of items changed in that comparison, for example, if there are 10 items and 8 had changes detected, the score will be 80.
- progress – the number of items in the comparison and the overall status
Return a list of objects in a project by a query
This call returns a list of objects (comparison and screenshots) that belong to a particular project.
Endpoint: /api/v1/project/[id]/query
Request method: POST
Method arguments:
- id (required) – the numeric id of the project.
- type – either screenshot or comparison (omit this to return both types of objects)
- title – full or partial title of the screenshot or comparison (omit this to return all objects)
Example: curl --header 'x-api-key: 790805643641389d125d0ce014b72b20' --request POST https://localhost:8888/trakr/api/v1/project/310/query --data '{"title":"PR 11"}'
Example result {"status":"success","result":{"398":"screenshot","399":"screenshot","400":"comparison}}
The result is a set of JSON key/value pair with the key being the object type (screenshot/comparison) and the value equals to the object id.
Delete an object in Trakr
This API call will delete an object in Trakr
Endpoint: /api/v1/delete/[object_type]/[id]
Request method: GET
Method arguments:
- object_type (required) – The type of object. the value can be: screenshot, comparison, project
- id (required) – the numeric id of the object.
Example: curl --header 'x-api-key: cf160643934c3628fc736f7f6f124f35' --request GET https://app.trakr.tech/api/v1/delete/screenshot/123
Create a new screenshot collection
This API call will create a screenshot collection in an existing project on the platform. The API caller user must be the owner of the project or have access to create screenshot collection in the project.
Endpoint: /api/v1/project/[id]/screenshot
Request method: POST
Method arguments:
- id (required) – the numeric id of the project.
- environment (optional) – the project (website) environment, accepted values are: production|staging|development. If this is not passed int it will default to the production environment. This argument is passed in as part of the POST data.
- title (optional) – Specify the screenshot collection title.
- username (optional) – Enter the username associated with this website environment if applicable. (Learn more)
- password (optional) – Enter the password associated with this website environment if applicable. (Learn more)
Special note
If you have configured the project environment with user login, then the username and password arguments become required in the API call.
Example: curl --header 'x-api-key: cf160643934c3628fc736f7f6f124f35' --request POST https://app.trakr.tech/api/v1/project/41/screenshot --data '{"environment":"production", "title": "post update (July 30)"}'
Compare with the last screenshot collection (In the same environment)
This API call will create a new screenshot collection (in the specified environment) and then compare with the last screenshot collection created in the project. If there is no previous screenshot collection in the project, it will simply create a new screenshot collection.
Endpoint: /api/v1/project/[id]/compare_self
Request method: POST
Method arguments:
- id (required) – the numeric id of the project.
- environment (optional) – the project (website) environment, accepted values are: production|staging|development. If this is not passed int it will default to the production environment. This argument is passed in as part of the POST data.
- username (optional) – Enter the username associated with this website environment if applicable. (Learn more)
- password (optional) – Enter the password associated with this website environment if applicable. (Learn more)
Special note
If you have configured the project environment with user login, then the username and password arguments become required in the API call.
Example: curl --header 'x-api-key: cf160643934c3628fc736f7f6f124f35' --request POST https://app.trakr.tech/api/v1/project/41/compare_self --data '{"environment":"development"}'
Compare between 2 pre-defined environments (For example, production vs. staging)
This API call will compare the latest screenshot collections in the given environments. If there is no screenshot collection available, it will create them first.
Endpoint: /api/v1/project/[id]/compare_environments
Request method: POST
Method arguments:
- id (required) – the numeric id of the project.
- environment1 (required) – the project (website) environment, accepted values are: production|staging|development.This argument is passed in as part of the POST data.
- environment2 (required) – the project (website) environment, accepted values are: production|staging|development.This argument is passed in as part of the POST data.
- username1 (optional) – Enter the username associated with this project environment1 if applicable. (Learn more)
- password1 (optional) – Enter the password associated with this project environment1 if applicable. (Learn more)
- username2 (optional) – Enter the username associated with this website environment2 if applicable. (Learn more)
- password2 (optional) – Enter the password associated with this website environment2 if applicable. (Learn more)
Special note
If you have configured the one of the project environment with user login, then the username(1 or 2) and password(1 or 2) arguments become required in the API call.
Example: curl --header 'x-api-key: cf160643934c3628fc736f7f6f124f35' --request POST https://app.trakr.tech/api/v1/project/41/compare_environments --data '{"environment1":"production", "environment2":"staging"}'
Compare between a pre-defined screenshot collection and a build environment
This API call is designed to create a comparison test between a screenshot collection in a predefined environment such as production or staging against a (continuous integration) build environment.
Endpoint: /api/v1/project/[id]/compare_build
Request method: POST
Method arguments:
- id (required) – the numeric id of the project.
- build_url (required) – The base URL for the build (from CI)
- environment – One of the pre-defined environment (production/staging/development)
- collection_id – The id of an existing screenshot collection used as the baseline (before) screenshot in the comparison test
- comparison_name (optional) – The name (title) of the comparison test generated
- title (optional) – The name (title) of the screenshot collection if we did not specify a collection_id in this call
Note: You must supply either a (pre-defined) environment or collection_id to be used as the baseline (before) screenshot. If you supply an environment, the API will either use the last available screenshot collection in that environment or create a new screenshot collection in that environment to compare with the build environment.
Example1: Create a comparison test between the production environment and a build environment.
curl --header 'x-api-key: c1702607d373687432a34e7db2ff4c39' --request POST https://app.trakr.tech/api/v1/project/310/compare_build --data '{"environment":"production", "build_url": "http://build123.example.com"}'
Example2: Create a comparison test between an existing screenshot collection and a build environment.
curl --header 'x-api-key: c1702607d373687432a34e7db2ff4c39' --request POST https://app.trakr.tech/api/v1/project/310/compare_build --data '{"collection_id":"321", "build_url": "http://build123.example.com", "comparison_name": "foo vs. bar"}'
Perform a quick comparison
This API call will quickly perform comparisons for 2 URLs. This method is useful when you are trying to compare different “build” in continuous integration, continuous deployment environment. Please note that your custom environment SHOULD contain the same path/URIs as your other environments set up on the project.
Endpoint: /api/v1/project/[id]/compare_custom
Request method: POST
Method arguments:
- id (required) – the numeric id of the project.
- url1 (required) – A valid URL (base URL), for example (https://build154.example.com). This argument is passed in as part of the POST data.
- url2 (required) – A valid URL (base URL), for example (https://build155.example.com). This argument is passed in as part of the POST data.
- comparison_name (optional) – Name of the comparison. This argument is passed in as part of the POST data
Example: curl --header 'x-api-key: cf160643934c3628fc736f7f6f124f35' --request POST https://app.trakr.tech/api/v1/project/41/compare_custom --data '{"url1": "https://build154.example.com", "url2": "https://build155.example.com"}'
Example result {"status":"success","result":{"message":"Task of comparing https:\/\/build154.example.com and https:\/\/build155.example.com has started","url":"https:\/\/app.trakr.tech\/comparisons\/c-mar-3-2018-golf-vs-c-mar-3-2018-victor","id":"127"}}
The result set is a JSON with the following attributes
- id – the comparison id
- url – URL to view the comparison
Create a new project
This call will create a new project on Trakr
Endpoint: /api/v1/project
Request method: POST
Method arguments: Arguments for this method needs to be passed in a nested JSON, which will be denoted with sub-list below:
- production
- url (required) – The base URL for the project (in its production/live environment), e.g. http://www.example.com (no trailing slash)
- username – If the URL has basic authentication (.htpasswd), the associated username
- password – If the URL has basic authentication (.htpasswd), the associated password
- uris (required) – a nested list of URIs (e.g. /contact), you must supply at least one URI
- [uri1]
- [uri2]
- [uri3]
- …
- title – Title of the project (if not given, the URL of the production environment will be used)
- staging
- url – The base URL for the staging environment
- username – If the URL has basic authentication (.htpasswd), the associated username
- password – If the URL has basic authentication (.htpasswd), the associated password
- development
- url – The base URL for the staging environment
- username – If the URL has basic authentication (.htpasswd), the associated username
- password – If the URL has basic authentication (.htpasswd), the associated password
- schedule
- interval – interval to take a screenshot collection in the project in days, for example, “1” will take a screenshot collection every day, max value is 14.
- comparison – if the system should create a comparison after taking the screenshot collection (0 or 1)
- notification
- emails – a nested list of email addresses to receive notifications when new screenshot/comparisons are complete in the project
- [email 1]
- [email 2]
- [email 3]
- …
- emails – a nested list of email addresses to receive notifications when new screenshot/comparisons are complete in the project
Example: curl --header 'x-api-key: cf160643934c3628fc736f7f6f124f35' --request POST https://app.trakr.tech/api/v1/project/ --data '{"production":{"url":"https:\/\/www.w3.org"},"staging":{"url":"https:\/\/staging.w3.org","username":"test","password":"123456"},"uris":["\/","\/standards","\/participate\/"],"title":"W3C website","schedule":{"interval":1,"comparison":1},"notification":{"emails":["john@email.com","jane@email.com"]}}'