API documentation

Terms of use and privacy policy

API reference

The Violinist API is using the JSON:API specification for its API. It uses standard HTTP response codes and verbs.

Authentication

Authenticating through the Violinist API is a matter of using a token from your version control hosting provider. For example, if you use Gitlab as your hosting provider, you would need a Gitlab token as an authentication mechanism.

The token should be sent in all requests, and it should be placed in a header called X-Violinist-Provider-Token. If you fail to provide such a header, or if the token does not authenticate you properly towards the resource you are trying to create, you will receive a 403 Forbidden HTTP response code.

What provider does the token belong to?

If you do an API call to POST a resource, it will be obvious from the request what provider the token should belong to (as you will probably include the URL to a repo). However, if you are using the API for example to GET a specific project, or even list all your projects, the HTTP request will not contain enough information to guess where the token belongs (for example Gitlab). For that reason you are required to send this information in another special header called X-Violinist-Url. In other words, sending the header is not always required but never hurts. So why not just send it?

Authenticating via Bitbucket

To authenticate via Bitbucket you have to use an access token. To get an access token, you would typically have to have a token on a site like this one. An access token expires, so if you want to use the API programatically, you typically want to look at using a refresh token to get a fresh token to use. If you have already registered on violinist.io with Bitbucket, click on this button to show your current access token:

Authenticating via Gitlab

To authenticate via Gitlab you can use a Personal Access Token. You can create this in your account settings at Gitlab. The scopes needed are api, read_user, read_api and read_repository.

Authenticating via Github

The easiest way to authenticate via Github is to create a personal access token (PAT) and use this. You can create this in your account settings at Github. The scopes needed are repo and user.

Teams

If you are using the API to create a project, you can also specify a team to add the project to. If you have only one team, this is not strictly necessary, as the team will be automatically populated based on your authentication. If you belong to more than one team, however, then the team will in fact be required.

To find all the teams you are a member of, you can use the issue a GET to the /api/node/team endpoint. This will return a list of all the teams you are a member of. The response will look something like this:

{
  "jsonapi": {
    "version": "1.0",
    "meta": {
      "links": {
        "self": {
          "href": "http://jsonapi.org/format/1.0/"
        }
      }
    }
  },
  "data": [
    {
      "type": "node--team",
      "id": "ee4c7e53-b794-46c7-b6b3-fb9bbfeb2692",
      "links": {
        "self": {
          "href": "https://violinist.io/api/node/team/ee4c7e53-b794-46c7-b6b3-fb9bbfeb2692?resourceVersion=id%3A5"
        }
      },
      "attributes": {
        "title": "My team"
      }
    }
  ],
  "links": {
    "self": {
      "href": "https://violinist.io/api/node/team"
    }
  }
}

In this example we are looking for the UUID value of the team (in the field id), so specifically in this example that would mean we want to take a note of ee4c7e53-b794-46c7-b6b3-fb9bbfeb2692.

Lastly, this UUID value should be included in the payload when creating a project. The payload should look something like this:

{
  "data": {
    "type": "node--project",
    "attributes": {
      "repo": "https://gitlab.com/user/repo"
    },
    "relationships": {
      "team": {
        "data": [
          {
            "type": "node--team",
            "id": "ee4c7e53-b794-46c7-b6b3-fb9bbfeb2692"
          }
        ]
      }
    }
  }
}

HTTP Response codes

Violinist uses conventional HTTP response codes to indicate if a request results in a success or a failure. In practice this means the following:

• Response code 201: The project was created!
• Response code 403There was an authentication error. Probably you either do not have access to the repo, your authentication header was not valid, or you have used more than your allowed number of projects on violinist.io.
• Response code in the 4xx range: There was a client error. Usually meaning the request payload was not as expected. This could mean the composition of the JSON for example. Or maybe the URL to the repo you are trying to add was malformed or unsupported.
• Response code in the 5xx range: There was a temporary server error. This usually means you can try again later or be in touch if the problem persists.

Content types

The only supported content type is application/vnd.api+json

Interactive example

{
  "data": {
    "type": "node--project",
    "attributes": {
      "repo": "https://gitlab.com/user/repo"
    }
  }
}

$ curl -H "X-Violinist-Provider-Url: https://gitlab.com" -H "X-Violinist-Provider-Token: my-token" -H "Content-type: application/vnd.api+json" http://violinist.io/api/node/project --data '{
  "data": {
    "type": "node--project",
    "attributes": {
      "repo": "https://gitlab.com/user/repo"
    }
  }
}'