API References

Alpacon provides RESTful API to control and manage the states of servers. The root index for API is under /api/. You can access the API via https://alpacon.io/api/ (opens in a new tab) using a web browser. Login using your account credentials to see all supported APIs.

Global information

HTTP methods

Alpacon REST API supports standard HTTP methods to identify and manipulate resources on alpacon.

• GET: List or retrieve resources
• POST: Create a resource
• PUT: Update a resource
• PATCH: Partially update a resource
• DELETE: Delete a resource

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

Our API generally returns following status codes if the request was successful.

• 200 OK: API request was successful. (By GET, PUT, or PATCH)
• 201 CREATED: A resource has been created. (By POST)
• 204 NO CONTENT: A resource has been deleted. (By DELETE)

We may return following status codes if the request has failed.

• 400 Bad Request: The request is malformed, meaning that there are some errors in request data. Proper error messages are returned as response data. Clients should handle this messages so that users can correct the error.
• 401 Unauthorized (opens in a new tab): The user is not authenticated or lacks valid authentication information. In this case, the client must ensure that the request clearly contains authentication information. If you are not authenticated, you must request one, including the appropriate authentication information.
• 403 Forbidden (opens in a new tab): The user is not authenticated or does not have proper permission to do the request. In this case, clients can check whether the user is authenticated via /api/auth/is_authenticated/. If the request failed even while the user is authenticated, clients may redirect the user to a 403 error page.
• 404 Not Found: The requested resource does not exist. Clients may redirect the user to a 404 error page.
• 405 Method Not Allowed: Requested HTTP method is not allowed. This error should be handled in development process and should not be shown to the end user.
• 500 Server Error: There is something wrong in the server. Clients may redirect the user to a 500 error page.

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.