API Documentation

Introduction

StaticCling offers a full REST API for integration with your custom application or environment. This document describes version 1 of the public API.

Versioning

The StaticCling API and servers use the Semantic Versioning scheme to quickly infer state and status, and to avoid client breakage during updates.

Historically, StaticCling has always offered a loose collection of URLs that performed the most basic functions. These lacked a cohesive interface, documentation, and any advanced functionality. Those don't count as an official API, so we restarted with version 1. The old stuff is legacy and no longer supported.

Specifics:

• The version is divided into three parts - X.Y.Z (major, minor, and patch) level.
• Patch level increments don't affect the API at all.
• Minor level increments won't affect existing clients, they only include backwards compatible changes and additions.
• Major level increments will require clients to update, and the API endpoint (/api/v1) will change accordingly.
• The major version of StaticCling will match the version of the API currently in use.
• The current server version is StaticCling 1.2.0 (build ec64b33e516b), and the current API version is 1.

Parameters

Many API requests require parameter arguments to function correctly. (Scroll down to see specific parameter requirements for each endpoint.) You can send parameters in a variety of formats, but it's probably best to pick one method and stick to it for the entirety of the conversation.

• GET requests that need parameters can use regular URL query arguments.
• POST, PUT, and DELETE requests can send the parameters in the body of the request in a variety of formats:
  • YAML: Set your Content-Type to text/x-yaml or application/x-yaml
  • JSON: Set your Content-Type to text/javascript or application/json
  • HTTP Encoded Form: Set your Content-Type to application/x-www-form-urlencoded

Data Formats

Just as you can send us parameters in a variety of formats, you can receive serialized responses in various formats as well. This is done via the Accept header in your request.

• YAML: Set your Accept header to text/x-yaml or application/x-yaml
• JSON: Set your Accept header to text/javascript or application/json
• HTML: Though this isn't serialized, it's still an available option. (You're looking at it right now.) Probably not a good one if you're writing a client, however. Set your Accept header to text/html.
• Plain text: Setting your Accept header to text/plain will spit out some form of response, but it likely won't be structured data. Best to stick with the JSON or YAML options if you expect consistency.

Authentication

Various endpoints require valid authentication data in order to accept the request. For these endpoints, a challenge/response system allows authentication to take place without sending passwords across the network in the clear.

• First, request a challenge token.
• Create a response, which is a SHA256 of the challenge and the SHA256 hashed password concatenated together.
  SHA256( challenge + SHA256(password) )
• Return the challenge, the response, and your account name as parameters to your request.

Challenge tokens cannot be used more than once, and are only valid for a limited time frame. (Currently 30 seconds.)

Sessions

For endpoints that require authentication, you can normally just send a valid challenge response along with each request. If you're performing a lot of requests, or making a client that has the concept of "logging in", then you can make things a little more efficient by opening a session. Because a session key can be potentially sniffed and replayed, it's probably a good idea to ensure you're using SSL if on an untrusted network.

A session is, unsurprisingly, created using a POST to the /session endpoint, with an initial set of valid challenge/response parameters. If successful, you'll get back a session token linked to your account. For all subsequent requests, you can send this token as the value of a sc-session cookie to satisfy authentication requirements.

When finished, send a DELETE to the same endpoint with the cookie set to permanently close the session.

HTTP Return Codes

Unless otherwise specified, all endpoints use the following HTTP return codes to express success or error states:

• Successful create (POST): CREATED (201), along with a Location header directing you to the newly created resource.
• Successful update (PUT): NO-CONTENT (204)
• Successful delete (DELETE): OK (200), along with the serialized deleted object.
• Error condition, request: BAD-REQUEST (400), along with an array of errors describing the problem.
• Error condition, server: SERVER-ERROR (500), along with an array of errors describing the problem.

Rate Limiting

The default rate limit for calls to the REST API varies depending on the endpoint and whether or not you're authenticated. If you're going over the rate limit for an API call you'll receive a TOO_MANY_REQUESTS (429) HTTP error -- your client should catch this and act accordingly.

Examples

Opening, using, and closing a session

First, request a challenge token:

Request:
  GET /api/v1/challenge
  Accept: application/x-yaml
  Content-Type: application/x-yaml
  User-Agent: ExampleClient-o-Doom!

Response:
  HTTP/1.1 200 OK
  Content-Length: 116
  Content-Type: application/x-yaml; charset=UTF-8
  
  ---
  challenge: 1E4fd228daE1eEd6507d19deccf6d9c7fdX63...

Generate a valid response to the challenge, sending it as a POST to /session:

Request:
  POST /api/v1/session
  Accept: application/x-yaml
  Content-Type: application/x-yaml
  User-Agent: ExampleClient-o-Doom!
  
  ---
  challenge: 1E4fd228daE1eEd6507d19deccf6d9c7fdX63...
  response: cf85ca453813eaf0478542e76936298142d408...
  account: example

Response:
  HTTP/1.1 200 OK
  Content-Length: 47
  Content-Type: application/x-yaml; charset=UTF-8
  
  ---
  session: fb0f280f5a0061a71e7c4042e9e6814f

Use the session token to your heart's content, then remove it when done, as such:

Request:
  DELETE /api/v1/session
  Accept: application/x-yaml
  Cookie: sc-session=fb0f280f5a0061a71e7c4042e9e6814f
  Content-Type: application/x-yaml
  User-Agent: ExampleClient-o-Doom!

Response:
  HTTP/1.1 200 OK
  Content-Length: 47
  Content-Type: application/x-yaml; charset=UTF-8
  
  ---
  session: fb0f280f5a0061a71e7c4042e9e6814f

API Endpoints

• /api/v1/
• /api/v1/availability
• /api/v1/challenge
• /api/v1/ip
• /api/v1/accounts
• /api/v1/accounts/[name]
• /api/v1/records
• /api/v1/records/[id]
• /api/v1/resend-validation
• /api/v1/reset-password
• /api/v1/session
• /api/v1/stats

/api/v1/

The root of the API service.

Methods
GET	Provide introspection for the available API endpoints. Returns a_data_structure You're looking at it!

/api/v1/availability

Account availability status.

Methods
GET	Check if an account name is currently available for registration. Parameters Required account An account name. Optional (none) Returns available The account's current availability as a boolean.

/api/v1/challenge

Authentication tokens.

Methods
GET	Fetch a new authentication challenge. Returns challenge The challenge token.

/api/v1/ip

Retreive IP address information.

Methods
GET	Return your current IPv4 address, as the server sees it. Returns ip Your IPv4 address.

/api/v1/accounts

Account listings.

Methods	(Admin authentication required)
GET	Fetch all accounts. Returns an array of: name The unique username of the account. email The email address linked to the account. givenname The first name provided at signup time. surname The last name provided at signup, if any. date_signup The date and time the account was created. date_signup_approx A timespan description of date_signup, in English. date_modified The date and time the account last altered its records. date_modified_approx A timespan description of date_modified, in English. signup_ip The IP address used to register the account. active Boolean true if the account has modified records within the configured deactivation timespan. admin Boolean true if the account is marked as an administrator. immortal Boolean true if the account is marked as immortal. Immortal accounts aren't deactivated or removed for inactivity. locked Boolean true if the account is marked as locked, which is a state usually reserved for abusive or otherwise disabled accounts. Locked accounts are unable to login or change any state. verified Boolean true if the email address has been validated by a human.

/api/v1/accounts/[name]

Individual account management.

Methods	(Authentication required)
DELETE	Remove a specific account. The authenticated account must be an administrator. Parameters Required reason Audit trail, a description of why the account was deleted. Optional (none)
GET	Fetch a specific account. Unless the authenticated account is an administrator, the account being fetched must match the account currently authed. Returns name The unique username of the account. email The email address linked to the account. givenname The first name provided at signup time. surname The last name provided at signup, if any. date_signup The date and time the account was created. date_signup_approx A timespan description of date_signup, in English. date_modified The date and time the account last altered its records. date_modified_approx A timespan description of date_modified, in English. active Boolean true if the account has modified records within the configured deactivation timespan. admin Boolean true if the account is marked as an administrator. immortal Boolean true if the account is marked as immortal. Immortal accounts aren't deactivated or removed for inactivity. locked Boolean true if the account is marked as locked, which is a state usually reserved for abusive or otherwise disabled accounts. Locked accounts are unable to login or change any state. verified Boolean true if the email address has been validated by a human.
PUT	Modify an existing account. Permissions are fine-grained, and behavior differs between parameters. Parameters Required (none) Optional email Alter the linked email address for the account. This does NOT immediately change the email, but instead triggers a validation request to the new email address. givenname Alter the first name on the account. Only used for display. Authenticated account must be an administrator. surname Alter the last name on the account. Only used for display. Authenticated account must be an administrator. password Change the account password. active Boolean, set whether the account will be included in active DNS. This is normally adjusted automatically on record update activity. Authenticated account must be an administrator. immortal Boolean, removes an account from deactivation and expiration activity timers. Authenticated account must be an administrator. locked Boolean, freezes the state of the account and records under it. The account will be unable to login. Authenticated account must be an administrator.

/api/v1/records

DNS record creation and listings.

Methods	(Authentication required)
GET	Fetch all records for the authenticated account. Returns an array of: id The unique identifier for this record. type The DNS record type. (Either 'A' or 'NS'.) ip An IPv4 address this record resolves to. subdomain If this exists, the record is a subdomain under the authenticated account namespace. If it does not, the record refers to the top-level DNS namespace. active Boolean true if the record is resolvable via DNS. wildcard Boolean true if the record's namespace is wildcarded.
POST	Create a new DNS record. The URI can be found in the response Location header. Parameters Required ip An IPv4 address this record will resolve to. Optional account Create this record on behalf of an account other than the currently authed one. Requires administrator credentials. active Boolean, set whether this record will be immediately resolvable via DNS. Defaults to 'true'. subdomain A hostname, marking this record as a subdomain under the account namespace. The record defaults to the top-level (account name) namespace. type A string specifying the DNS record type. Either 'A" or 'NS', currently. Defaults to 'A'. wildcard Boolean, set the DNS namespace of the record to be wildcarded for all subdomain queries.

/api/v1/records/[id]

Individual DNS record management.

Methods	(Authentication required)
DELETE	Remove a record.
GET	Fetch a specific record. Returns id The unique identifier for this record. type The DNS record type. (Either 'A' or 'NS'.) ip An IPv4 address this record resolves to. subdomain If this exists, the record is a subdomain under the authenticated account namespace. If it does not, the record refers to the top-level DNS namespace. active Boolean true if the record is resolvable via DNS. wildcard Boolean true if the record's namespace is wildcarded.
PUT	Modify an existing DNS record. Parameters Required (none) Optional ip An IPv4 address the record will resolve to. active Boolean, set whether the record will be immediately resolvable via DNS. subdomain A hostname, marking the record as a subdomain under the account namespace. Setting to '-' places it within the top-level (account name) namespace. type A string specifying the DNS record type. Either 'A" or 'NS', currently. wildcard Boolean, set the DNS namespace of the record to be wildcarded for all subdomain queries.

/api/v1/resend-validation

Sends the account's unique validation link via email.

Methods	(Authentication required)
POST	Resend the original validation email to the signup address. There is no 'Location' header nor body in the return. A successful send will reply with a 204 (NO_CONTENT) status.

/api/v1/reset-password

Generate and send a password reset link to an account.

Methods
POST	Create a new, limited time link that allows a password reset, sending it immediately to the specified account. There is no 'Location' header nor body in the return. A successful send will reply with a 204 (NO_CONTENT) status. Parameters Required account The account name. Optional (none)

/api/v1/session

Session management.

Methods
DELETE	Remove a currently active session. Returns session The deleted session ID key.
POST	Create a new session. Parameters Required account The account name. challenge A challenge token. response A valid response to the challenge. Optional (none) Returns session The session ID key, to be used in the 'sc-session' cookie.

/api/v1/stats

Various account statistics.

Methods	(Authentication required)
GET	Generate an array of data points over the last 30 days, describing various pieces of account activity. Currently, only recent DNS activity is returned. Returns dns_activity An array of DNS lookups per hour. Times are in milliseconds since the epoch (suitable for javascript date objects.)