Wercker Releases API Reference Guide

Table of Contents

Part 1: Get Started

Part 2: Tasks

PART 1: Get Started

Quick Start

Set up your environment and use the REST API to create your first repository by performing the following tasks.

Step 1: Create a Wercker account

  1. Create an account with Wercker. See Creating an Account.
    Note the user name and password that you provide while creating the account. All examples in this document use Joe as the user name. You’ll need to provide this value to access the REST API.

Step 2: Create an Authentication Token for Wercker

  1. Log in to https://app.wercker.com using the user name and password that you provided while creating an account with Wercker.

  2. To create an authentication token using the Wercker user interface, navigate to https://app.wercker.com/profile/personal, and then click Personal tokens.

  3. Enter a name for the authentication token, and then click Generate. The name of the authentication token can be up to 30-characters.

  4. Note the generated value of the authentication token. Ensure that you store the value of the authentication token immediately as you cannot retrieve it later. You’ll need to provide this value to access the REST API.

Step 3: Create an Organization Using the Wercker User Interface

Create an organization using your Wercker user interface. See Organizations. Note the name of the organization that you have created. You'll need to provide this information while creating the authentication token to access the REST API. All examples in this document use acme as the name of the organization.

Step 4: Get the Required Roles Assigned

The owners team of an organization always has admin access. An admin has read and write access. See Roles and Permissions.

Step 5: Install cURL

You can access the REST API from any application or programming platform that correctly and completely understands the Hypertext Transfer Protocol (HTTP) and has Internet connectivity. The REST API uses advanced facets of HTTP such as secure communication over HTTPS, HTTP headers, and specialized HTTP verbs (POST, GET).

cURL, a command-line tool that you can use to invoke REST API calls by sending HTTP requests. The examples in this document use the cURL command-line tool to demonstrate how to access the REST API.

cURL is typically available by default on most UNIX-like hosts. For the instructions to install cURL on Windows, see the tutorial Installing cURL on Cygwin on Windows.

Note: Certain web browsers can also be used to send REST API calls. Support varies across vendors. Browser plugins may be needed for full support.

Many programming platforms (Java, Ruby, Perl, PHP, .NET, and so on) also meet these requirements, although some may require the use of third party libraries for full support. See your programming platform's documentation for guidance.

Step 6: Create an Authentication Token to Access the REST API

See Authentication Token.

Step 7: (Optional.) Create Your First Repository

After getting an authentication token, you can create a repository. See Create a Repository.

Step 8: (Optional.) Review the Details of Your First Repository

Check whether the repository is created, by sending a GET /api/v1/repos request. See List Repositories.

Send Requests

Use the following guidelines when sending requests using the REST API.

URL Structure

To perform operations on a resource by using REST API calls, you must specify the fully-qualified, unique URI of the resource.

The fully qualified URI of a resource is in the following format:

https://wcr.io/api/v1/{resource_base_path}/{organization_name}/{repository_name}

Where:

  • resource_base_path is the base URI of the resource. For example, for repository, the base URI is /repos.
  • organization_name is the name of the organization that you have created using the Wercker user interface. All repositories are created within the specified Wercker organization.
  • repository_name is the multi-part name of the repository.

Supported Methods

You can perform basic read and create operations on objects using standard HTTP method requests, as summarized in the following table.

HTTP Method

Description

GET

Retrieves information about the objects specified in the request URI.

POST

Creates an object.

Each object for which you can perform API calls is identified uniquely by its URI. Note that some of these methods may not be supported for certain objects.

Media Types

The following media types are supported by the REST API:

  • application/json

Supported Headers

The REST API supports the following headers that may be passed in the header section of the HTTP request or response.

Header

Description

Example

Accept:

With a few exceptions, the REST API returns JSON-encoded data in its responses. So the Accept: header must be set to indicate this.

Accept: application/json

Content-Type:

All the content in an HTTP request body sent to the API server must be encoded in JavaScript Object Notation (JSON). The API protocol version is also specified in the Content-Type: header in both request and response messages. The currently used content types is application/json.

The server specifies the expected version of the data in the response in the Content-Type: header.

Content-Type: application/json

Authorization:

The Authorization: header must be included with every request to the service. It must be set to the value of the authentication token that you create using the GET /api/v1/token HTTP request.

Authorization:Bearer $TOKEN

TOKEN is the name of the environment variable in which you store the authentication token. See Authentication Token.

Compression

Use compression on the REST resource request and response for improved performance. To use compression, include one of the following HTTP headers in the request: Accept-Encoding or Content-Encoding.

Status Codes

When you call any of the resources, the Response header returns one of the standard HTTP status codes defined in the following table.

Note: Success codes are documented in the topics that describe the individual methods.

HTTP Response Code

Error Description

4xx

APIClientError

A client side error, in line with 4xx errors in HTTP.

401

APIUnauthorizedError

The request requires user authentication or authorization.

403

APIForbiddenError

The server understood the request, but is refusing to fulfill it. Authorization will not help and the request should not be repeated.

404

APINotFoundError

The server hasn't found anything matching the Request-URI. No indication is given of whether the condition is temporary or permanent.

409

APIConflictError

The request could not be completed due to a conflict with the current state of the resource, or, in the case of a resource-creation call, the requested resource already exists in the system. You can either delete the existing object and create it afresh or create a new object with a unique identifier.

416

Requested Range Not Satisfiable

The request could not be completed as the range you have specified does not match the current range of the selected resource.

5xx

APIServerError

An internal error has occurred and the server is incapable of fulfilling the request.

500

APIUncaughtExceptionError

The server encountered an unexpected condition that prevented it from fulfilling the request. This error will return a reference code which you must note and supply when you contact Oracle Support.

503

APIServiceUnavailable

The server is currently unable to handle the request due to temporary overloading or maintenance. This is most likely a load-related condition, which should be alleviated after a short delay.

502

APIGatewayError

The connection between the API and the service layer is down. This is generally a temporary, most likely service failover-related, condition, which should be alleviated after a short delay.

Use cURL

cURL is an open source, command-line tool for transferring data with URL syntax, supporting various protocols including HTTP and HTTPS. The examples in this document use cURL to demonstrate how to access the REST API.

For information about downloading and installing cURL, see Quick Start. You must install a version of cURL that supports SSL.

For more information about authentication requirements, see Authentication Token.

After installing cURL, invoke cURL and specify one or more of the command-line options defined in the following table, as required, to direct its execution to use cURL to access the REST API:

cURL Option

Description

-d, --data @file.json

Identifies the request document, in JSON format, on the local machine.

-F, --form @file.json

Identifies form data, in JSON format, on the local machine.

-H

Defines one or both of the following:

  • Content type of the request document
  • Accept header

-i

Displays response header information.

-X

Indicates the type of request, such as DELETE, GET, HEAD, PATCH, POST, or PUT.

For example:

curl -i -X POST \
     -H "Authorization:Bearer $TOKEN" \
     https://wcr.io/{path}/{repo-path} \

The following example cURL command creates a repository named oracle-linux.

curl -i -X POST \
     -H "Authorization:Bearer $TOKEN" \
     https://wcr.io/api/v1/repos/acme/oracle-linux \

TOKEN is the name of the variable in which you store the authentication token. See Authentication Token.

Note: For information about the URLs to which you should send HTTP requests, see Send Requests.

Part 2: Tasks

Authentication Token

Create an Authentication Token Using Basic Authentication

GET /api/v1/token

API calls to the service require a valid authentication token. This request authenticates the specified user and returns an authentication token, which you can specify in subsequent API calls to the service.

Prerequisites

You must ensure that you complete the following steps before requesting for an authentication token. For more information about completing these steps, see Quick Start.

  1. Create a Wercker account.
  2. Create an authentication token using the Wercker user interface. Note the Wercker account name and the value of the authentication token. You'll need to provide this information while creating the authentication token.
  3. Create an organization using your Wercker user interface. See Organizations. Note the name of the organization that you have created. You'll need to provide this information while creating the authentication token.

To request for an authentication token and store the authentication token in an environment variable:

  1. Run the following command on your Linux host to base64 encode the Wercker username and value of the authentication token that you have created using the Wercker user interface.
     echo -n "Wercker_username:authentication_token_value" | base64 

    Example command

    echo -n "Joe:eb760ba01237c2bac2003f7c999ca3596da0dd18a5dcbc251d681bd43359db53" | base64

    The base64-encoded value of the user name and authentication token value is returned.

    Example response

    U3lsYWphSzplYjc2MGJhMDEyMzd...lkYjUz

    The example response has been truncated with ellipses (...) for readability.

  2. Note the base64-encoded value of the username and authentication token. You'll have to provide this value every time you want to create an authentication token.
  3. Get an authentication token using the base64-encoded value, as shown in the following cURL command example.

    Command syntax

    curl -i -X GET \
         -H "Authorization:Basic {base64-encoded-value}" \
         https://wcr.io/api/v1/token\?service\=wcr.io\&scope\=scope\=repository:{organization-name}:{access_rights_to_organization} \

    Where, you can specify the following values for access_rights_to_organization:

    • pull
    • push
    • pull,push
    • empty

    Example

    The following command creates an authentication token that you can use to make API calls to work with repositories in the acme organization.

    curl -i -X GET \
         -H "Authorization:Basic U3lsYWphSzplYjc2MGJhMDEyMzd...lkYjUz" \
         https://wcr.io/api/v1/token\?service\=wcr.io\&scope\=scope\=repository:acme:pull,push \

    Enter the command on a single line. Line breaks are used in this example for readability.

  4. In the response to the GET request, look for the value of the token parameter in the response, as shown in the following example.

    {
      "token": "eyJ0eXAiO...",
      "access_token": "eyJ0eXAiO...",
      "scope": "",
      "expires_in": 3600
    }

    The example response has been truncated with ellipses (...) for readability.

  5. Store the authentication token in an environment variable, as shown in the following example for a Linux host.

    export TOKEN="eyJ0eXAiO..."

    You must include a valid authentication token in the Authorization header while making subsequent API calls to the service.
    The expires_in response parameter specifies the number of seconds until this authentication token expires. When the authentication token expires, you'll have to create another authentication token.

Repository

A repository groups together different versions of an image with a common name, where each version is identified by a tag. Each repository is owned by an organization. See What is a repository in the Wercker UI.

Create a Repository

POST

/api/v1/repos/{path}

Creates an empty repository with name you specify for the path parameter. The repository that you create belongs to an organization in Wercker. Any images you subsequently push to ODX Registry that have the same name as the repository are grouped into that repository. For example, the acme/oracle-linux repository is owned by the acme organization, and contains images named oracle-linux. When you push an image with the name oracle-linux, it is grouped into the acme/oracle-linux repository. Each image in the acme/oracle-linux repository has a unique tag (for example, latest, 4.6.3 –20160823, 7.5.2).

Path Parameters

Parameter

Description

path

Specify the name of the repository to be created.

A repository name has at least two path components and they are separated by a forward slash (“/”) in the format {organization-name}/{multipart-repo-name}. The first part is the name of the organization in Wercker in which you are creating the repository. For example,

Repository names can contain only alphanumeric characters, dashes, underscores, and periods. The name must contain at least one lower case character. When you specify the repository name, ensure that a repository with the same name doesn't already exist. If such a repository already exists, another repository with the same name won't be created and the existing repository won't be updated.

The total length of a repository name, including slashes, must be less than 256 characters.

Type: string

Response

Success status: 201

See Status Codes for information about other possible HTTP status codes.

Example
cURL Command

The following example shows how to create a repository by submitting a POST request on the REST resource using cURL. When you create a repository, it is empty. For more information about cURL, see Use cURL .

Enter the command on a single line.

curl -i -X POST \
     -H "Authorization:Bearer $TOKEN" \
     https://wcr.io/api/v1/repos/acme/oracle-linux \
  • TOKEN is the name of the variable in which you stored the authentication token earlier. For information about retrieving the authentication token and storing it in a variable, see Authentication Token.

The repository is created but no response is returned. To check if your repository is created, you can send the List Repositories request.

List Repositories

GET

/api/v1/repos

Retrieves details of the repositories that match the specified query criteria. If you don't specify any query criteria, then details of all the repositories are displayed. The repositories are listed based on their creation date, with the most recent entries being listed first.

Query Parameters

Name

Description

n

Specify the number of repositories for which you want to retrieve details. For example, if you specify 10, then details of the last 10 recently created repositories are retrieved.

Required: no

Default: 100

Type: integer

last

Specify the date in DD-MM-YY format. Repositories that were created after the specified date are retrieved.

By default, this request retrieves details for the 100 repositories that were recently created. To retrieve information about more repositories, note the createdDate value of the last item that was returned when you sent this request. You can send this request again while specifying the value you noted down as a query parameter.

Required: no

Type: string

 

Success Response

Status: 200

Example

cURL Command

curl -i -X GET \
     -H "Authorization:Bearer $TOKEN" \
     https://wcr.io/api/v1/repos \
  • TOKEN is the name of the variable in which you stored the authentication token earlier. For information about retrieving the authentication token and storing it in a variable, see Authentication Token.
Example of Response Body

The following example shows the response body in JSON format.

{
  "repositories": [
    {
      "repoPath": "acme/oracle-linux",
      "tag": "master-590b2b1f7b6afc2cfcb146513cbc8cbd1697b5cc",
      "digest": "sha256:bd8bea9201e281d83221b60b13836b2a6488bcc0496c2465f6cfe26c9bb27d91",
      "fetchCount": 0,
      "sizeBytes": 2379811,
      "createdBy": "59b66aec24bc9f010046cfb6",
      "createdDate": "2017-08-11T14:39:52.136Z"
    },
    {
      "repoPath": "acme/windows",
      "fetchCount ": 0,
      "sizeBytes": 0,
      "createdBy": "59b66aec24bc9f010046cfb6",
      "createdDate": "2017-08-11 T14: 39:52.136 Z"
    }
  ],
  "next": null
}

Get a Repository

GET

/api/v1/repos/{path}

Retrieves details of the specified repository. It also returns metadata which you can't retrieved using the standard Docker API. You can use the retrieved information to build dashboards and display other interesting metrics about the repositories and images that are returned. For example, the fetchCount response parameter indicates the number of times an image was downloaded.

Path Parameters

Parameter

Description

path

Specify the multipart name ({organization-name}/{multipart-repo-name}) of the repository for which you want to retrieve the details.

Type: string

Success Response

Status: 200

Example

cURL Command

The following example shows how to retrieve details of a repository, /acme/oracle-linux, by submitting a GET request on the REST resource using cURL. For more information about cURL, see Use cURL.

Enter the command on a single line.

curl -i -X GET \
     -H "Authorization:Bearer $TOKEN" \
     -H "Accept: application/json" \
     https://wcr.io/api/v1/repos/acme/oracle-linux \
Example of Response Body

The following example shows the response body in JSON format. When there are no images in the repository, the response returned is [].

{
  "repoPath": "acme/oracle-linux",
  "tag": "master-590b2b1f7b6afc2cfcb146513cbc8cbd1697b5cc",
  "digest": "sha256:bd8bea9201e281d83221b60b13836b2a6488bcc0496c2465f6cfe26c9bb27d91",
  "fetchCount": 0,
  "sizeBytes": 2379811,
  "createdBy": "5950e2db41eaac01008cde4c",
  "createdDate": "2017-08-11T14:39:52.136Z"
}