Publisher API

{
  "version": 1,
  "links": [
    {
      "rel": "self",
      "href": "http://localhost:8080/publisher/api/v1"
    },
    {
      "rel": "environments",
      "href": "http://localhost:8080/publisher/api/v1/environments"
    },
    {
      "rel": "publications",
      "href": "http://localhost:8080/publisher/api/v1/publications"
    },
    {
      "rel": "messages",
      "href": "http://localhost:8080/publisher/api/v1/messages"
    }
  ]
}

The Publisher REST API uses the Hypermedia as the Engine of Application State (HATEOAS) principle. The main entry point is the only URL that REST clients need to know beforehand. All other endpoints provided by the API can be discovered using the resource links in the resource representations returned by the server.

Database and Studio environments

The REST API defines two kinds of environments:

• database environments - regular environments on which applications may be published or unpublished
• studio environments - studio instances from which applications may be read but may not be published or unpublished

In the current version, a single studio environment is supported, and this environment has a fixed name: studio. In order to obtain applications from a studio environment, the REST API exposes a series of endpoints which allow navigating the repositories, branches, revisions and applications available in Studio. These endpoints are available as links on the studio environment resource. 

Database environments contain application exports. Each database environment resource contains a link to the endpoint from where the application exports on that environment can be obtained.

Authentication in the Publisher REST API

The REST API uses the OAuth2 Resource Owner Password Credentials Grant for authentication. With this grant type, both the REST client (the client application) and the user (resource owner) need to authenticate with the Publisher before being able to use the REST API. In the current version, a single REST client is supported. See 'Installing Publisher' for details on how to configure the REST client credentials.

The endpoint for authentication is /oauth/token. This endpoint is responsible with issuing authentication tokens that can be used to access the Publisher REST API. To obtain an authentication token, the REST client must POST a request to this endpoint and provide the following information:

• the REST client credentials, using Basic HTTP Authentication
• the resource owner credentials, using the username and password request parameters
• the grant type, using the grant_type request parameter, which must have the value password (other grant types are not supported in the current version)

POST http://localhost:8080/publisher/oauth/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Basic cmVzdGFwcDoxMjM=
Content-Length: 47
Host: localhost:8080
Request parameters:	?grant_type=<password>&username=<the_user>&password=<the_password>

If authentication is successful, the server will respond with status 200 OK and a JSON object containing the access token and the time in seconds until the token expires:

{
	"access_token":"0bcda8e4-2f16-487f-b6e6-1fc86f9fb6a3",
	"token_type":"bearer",
	"expires_in":2698
}

If authentication fails, the server will respond with status 401 Unauthorized, and a JSON object with details about the error.

Once an access token has been obtained, it must be transmitted with all requests to the Publisher REST API as an HTTP bearer token:

GET http://localhost:8080/publisher/api/v1/environments HTTP/1.1
Authorization: Bearer 0bcda8e4-2f16-487f-b6e6-1fc86f9fb6a3
Host: localhost:8080

The same token may be reused for multiple requests until the token expires. When a request is made with an expired token the server will respond with status 401 Unauthorized and a JSON object which details the reason (expired token).

{
  "error": "invalid_token",
  "error_description": "Access token expired: 0bcda8e4-2f16-487f-b6e6-1fc86f9fb6a3"
}

Client implementations must obtain a new token in order to continue using the REST API.

Publishing, Unpublishing, Approving and Rejecting Applications

In order to publish an application export to a (database) environment, the REST client must create a Publication resource and POST it to the publications endpoint (the URL of the endpoint is available as a link on the API entry point). The required fields are:

• sourceEnvironment - the source environment,  the application export is read from this environment
• destinationEnvironment - the environment the application export is published to. Must not be a studio environment.
• projectId - if sourceEnvironment is a studio environment, this field must be provided and must contain the repository, branch, revisionId and application to be published, otherwise it should not be provided
• exportId - if sourceEnvironment is a database environment, this field must be provided and must contain the id of the application export on the source environment, otherwise it should not be provided
• action - for publishing, the value of this field must be "publish"
• status - for publishing, the value of this field must be "requested"

Depending on the type of the source environment, either the projectId or the exportId must be provided. These fields are mutually exclusive.

If the destination environment doesn't require approval, the application export will be published to the destination environment immediately and the server will respond with status 204 No Content. The POSTed resource will not be stored on the server.

If the destination environment requires approval, the POSTed resource will be stored on the server. The server responds with status 201 Created and the stored resource. The URL to the stored resource is available in the self link and in the Location header.

In order to unpublish a application export from a (database) environment, the REST client must create a Publication resource and POST it to the publications endpoint. The required fields are:

• sourceEnvironment - the database environment from which the application export is to be unpublished. Must not be a studio environment
• exportId - the id of the aplication export on the source environment
• action - for unpublishing, the value of this field must be "unpublish"
• status - for unpublishing, the value of this field must be "requested"

If the source environment doesn't require approval, the application export will be unpublished immediately and the server will respond with status 204 No Content. The POSTed resource will not be stored on the server.

If the source environment requires approval, the POSTed resource will be stored on the server. The server responds with status 201 Created and the stored resource. The URL to the stored resource is available in the self link and in the Location header.

In order to approve a publish or unpublish request, the REST client must read the Publication resource, update its status field from "requested" to "approved" and PUT it to the URL defined in the self link of the resource. The required fields are:

• action - the value of this field must be "publish" or "unpublish" depending on what action is being approved
• status - for approving, the value of this field must be "approved"

The server will verify that the intent of the approver (provided in the action field) matches the intent of the publisher (stored in the database). In case of success, the server will respond with status 204 No Content.

In order to reject a publish or unpublish request, the REST client must read the Publication resource, update its status field from "requested" to "rejected" and PUT it to the URL defined in the self link of the resource. The required fields are:

• action - the value of this field must be "publish" or "unpublish" depending on what action is being approved
• status - for rejecting, the value of this field must be "rejected"

Batch Publishing, Unpublishing, Approving and Rejecting

The Publisher REST API also provides an endpoint for publishing, unpublishing, approving or rejecting multiple applications in one request.

The endpoint URL for batch publications is the same as for the single variant, but uses the application/vnd.blueriq.batch+json media type. The application/vnd.blueriq.batch+json media type is simply an array of publication resources. In order to publish a single application, a Publication resource with media type application/json should be POSTed to the endpoint, and in order to publish a batch of applications, an array of Publication resources with media type application/vnd.blueriq.batch+json should be POSTed to the same endpoint.

The batch endpoint imposes a number of restrictions:

• publish, unpublish and approve/reject actions are mutually exclusive in one batch (it is not possible to mix publish, unpublish and approve/reject actions)
• it is not possible to publish from multiple source environments in the same batch
• it is not possible to publish to multiple destination environments in the same batch

Resources in batch requests have the same mandatory fields as the single requests. For batch approving or rejecting the id field is also mandatory.

The responses of the server are similar to the responses to single requests, except when the server responds with 201 Created, the response will contain an array of created Publication resources instead of a single resource. In this case the URL to each resource is available in the self link of each resource, the Location header is not available.

Interactive API documentation

The Publisher also includes an interactive documentation for the REST API. This documentation may be accessed at /docs/index.html. Before being able to try requests, an access token needs to be generated by filling out the username and password fields with valid Publisher credentials and clicking the Generate Token button. When prompted for Authorization, the client credentials must be provided (as defined in publisher.properties).