The ideal time to automatically run API and web app tests is immediately after a deployment. Using the Assertible deployments API, you can run tests for a web service as part of your continuous-integration or delivery pipeline and track deployments to specific versions of your application.

If the code for your web service is hosted on GitHub, you can also create status checks and deployment events for commits and pull requests.

GitHub logo

Check out our GitHub integration


Deployments API Diagram

The easiest way to create a deployment is to run a simple curl command from your continuous integration pipeline or deployment process:

VERSION=`git log -n 1 --pretty=format:"%H"`
SERVICE=ASSERTIBLE_SERVICE_ID

curl -u $ASSERTIBLE_API_TOKEN: -XPOST 'https://assertible.com/deployments -d'{
    "service" : "'"${SERVICE}"'",
    "environmentName" : "production",
    "version" : "'"${VERSION}"'"
}'

See the examples for more examples.

GitHub

When you post a deployment to Assertible, it's possible to propogate the test statuses and deployment details to GitHub pull requests (and other refs & branches like master).

Assertible GitHub status check

For example, in the picture above, a deployment is created on assertible-staging with a direct link to the staging environment URL using the View deployment button, as well as the status of tests directly in the pull request checks under CircleCI.

Connect your web service to GitHub:

All you need to do to start creating GitHub deployments and status checks is to connect your web service to GitHub and use the github: true parameter in the call to POST /deployments.

When the github: true parameter is used, Assertible executes tests and also posts deployments and statuses to the GitHub API for the ref you provide in the deployment script.

If you are using Heroku to deploy your code from GitHub, you do not need to manually POST a deployment to Assertible. Heroku will create deployment events for the deployments and Assertible will recieve the events and run your tests. Your web service only needs to be connected to the correct repository.

External GitHub deployment integrations

If you are deploying code using a continuous delivery service like Heroku Pipelines or Heroku Review Apps, deployment events are already posted to the repository for you automatically. See our blog Automate smoke tests for a Go API on Heroku for a more detailed example.

Deployments API examples

Successful request

If the request succeeds, it will respond with the unique id of the deployment:

curl -XPOST 'https://assertible.com/deployments -d'{
    "service" : "123e4567-e89b-12d3-a456-426655440000",
    "environmentName" : "production",
    "version" : "v1.2"
}'
{"id":"caacafdc-8ddc-4245-a0f4-f6715c5d9478"}

Failed request

If creating the deployment fails, an error will be returned:

curl -XPOST 'https://assertible.com/deployments -d'{
    "service" : "123e4567-e89b-12d3-a456-426655440000",
    "environmentName" : "staging",
    "version" : "v1.2"
}'
{"code":"InvalidRequestError","message":"Cannot parse request body\n\"Error in $: key \\\"service\\\" not present\"\n"}

GitHub deployment

If the request succeeds, it will respond with an empty JSON object:

curl -XPOST 'https://assertible.com/deployments -d'{
    "service" : "123e4567-e89b-12d3-a456-426655440000",
    "environmentName" : "production",
    "version" : "v1.2",
    "ref" : "abcdef12345",
    "github" : true
}'
{}

Parameters

These parameters can be used in a request to POST /deployments:

  • api

    The web service (API) id. This can be found in the Assertible dashboard under the Deployments tab (look for Bash / Command-line).

  • version

    A unique textual representation of the application version. For example v1.0 or even a commit reference like cc0ab3f.

  • environmentName optional

    The environment name. Defaults to production when no environmentName parameter is specified.

    The environmentName must match a valid environment for the target web service. See our environments documentation for more information.

  • ref optional

    A source control reference.

  • url optional

    An external url for viewing further details about the deployment.

  • github optional

    If the github parameter is true, Assertible will create deployment events and corresponding status checks for the ref.

    Your web service must be connected to a GitHub repository to use this parameter.


If the POST request is made twice, the deployment is updated. This only has an impact for "optional" parameters like ref or url. A unique deployment is represented by the service, environment name, and version combination.


Automate your QA pipeline

Define and test your web service with Assertible Track and test API deployments across environments Schedule API monitoring and failure alerts

Reduce bugs in web applications by using Assertible to create an automated QA pipeline that helps you catch failures & ship code faster.

Sign up for free