API reference

Alpacon provides a RESTful API to control and manage the states of servers. The root path for the API is /api/.

API endpoint

Your workspace has a dedicated API endpoint:

https://<workspace>.<region>.alpacon.io/api/

Where:

<workspace>: Your workspace slug
<region>: Your workspace region (assigned at creation)

Example: https://mycompany.us1.alpacon.io

💡 Finding your endpoint: Go to Personal Settings to view your complete workspace endpoint URL.

All API examples in this documentation use https://your-workspace.us1.alpacon.io as a placeholder. Replace it with your actual workspace endpoint.

Authentication

All API requests require an API token. Include it in the Authorization header:

Authorization: token="alpat-xxxxxxxxxxxxxxxxxx"

Create and manage tokens on the API tokens page, or via the Alpacon web console under Personal Settings > API tokens.

Global information

HTTP methods

Method	Usage
`GET`	List or retrieve resources
`POST`	Create a resource
`PUT`	Replace a resource entirely
`PATCH`	Update specific fields of a resource
`DELETE`	Delete a resource

For more details, see the MDN HTTP methods reference.

URL structures

We have the following API structures.

List or create: /api/<collection>/<resource>/
Retrieve, update, or delete: /api/<collection>/<resource>/<id>/
Extra actions: /api/<collection>/<resource>/<id>/<action>/

For example, GET /api/iam/users/a540bf0f-8b37-4f03-8546-dd71c6b03329/ retrieves a user’s state.

Please note that all urls end with /.

Status codes

Success codes:

Code	Meaning	Typical method
`200 OK`	Request succeeded	`GET`, `PUT`, `PATCH`
`201 Created`	Resource created	`POST`
`204 No Content`	Resource deleted	`DELETE`

Error codes:

Code	Meaning
`400 Bad Request`	Invalid request data. See error messages for field-level details.
`401 Unauthorized`	Not authenticated. Provide valid credentials or token.
`403 Forbidden`	Permission denied. The authenticated user lacks required permissions.
`404 Not Found`	Resource does not exist.
`405 Method Not Allowed`	HTTP method not supported on this endpoint.
`500 Server Error`	Internal server error.

For the full list of HTTP status codes, see the MDN HTTP status reference.

Error messages

As noted above, alpacon will respond with error messages on 400 Bad Request. Alpacon provides field-level errors and non-field errors as a dictionary.

For example, when you are changing a user’s password, if the password does not pass the server-side validation, you will see the following error messages. Note that the field name, password, is used as the key for error messages. Clients should parse and display these messages properly so that they can correct the required fields.

HTTP 400 Bad Request
Allow: GET, PUT, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json
Vary: Accept

{
  "password": [
    "This password is too short. It must contain at least 8 characters.",
    "This password is too common.",
    "This password is entirely numeric."
  ]
}

Non-field errors are for object-level validation. For example, suppose you are about to delete an owner of a group. Alpacon will check whether he or she is the only owner of the group as there should be at lease an owner in a group. If the validation fails, we will respond with the following error message. As this error does not belong to a specific field, we use the key, non_field_errors.

HTTP 400 Bad Request
Allow: GET, PUT, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json
Vary: Accept

{
  "non_field_errors": [
    "You are the only owner of the group. Add another owner to proceed."
  ]
}

Alpacon features

Following documents describe the details about each collection of API.