Clusterducks

API Documentation

There are three APIs in clusterducks v0.9.2 and perhaps more in the future when device agent software warrants such complexity.

  • Panel API
    • Exposed via https://panel.example.com/api/ (newapi.php)
  • Client API
    • Exposed via http(s)://storagenode/api/
    • Available to panel
    • Available for LAN clients
  • Legacy APIs for panel + client
    • Exposed via api.php for panel

Though clusterducks exposes an API that can be consumed by REST clients, the API itself is not strictly RESTful - our output does not satisfy the HATEOAS constraint that essentially means pure XML will be used in the API with full hypermedia awareness. Our API may be called REST-like.

Ultimately, these distinctions are mostly philosophical for the project. What does matter is that a consistent and reliable API interface is exposed that utilizes as many features of its transport layer(s) as possible.

clusterducks API has the following characteristics:

  • Consistent, versioned URI structures
    • https://panel.example.com/api/v0.9.2/<endpoint>/<objectid>
  • Meets REST requirement for utilization of transport features
    • HTTP GET will only ever retrieve data
    • HTTP DELETE is used to remove objects
    • HTTP PUT is to be used when creating an object with an ID
    • HTTP POST is used to create, replace or partially update an object
    • HTTP PATCH is for supposed to be for partial record updates but we're not using it
  • Returns valid HTTP responses for requests
    • Request for non-existing resource gives 404 Not Found
    • Incomplete PUT requests return 400 Bad Request
    • Read-only resources return 405 Bad Method (i.e. using POST on GET method)
  • Requests to an endpoint without any arguments will typically list available objects attached to the endpoint. i.e. "users" endpoint will list all users (if the caller has required credentials)
  • Append a file extension to the API URI to change the output format
    • Does not utilize HTTP Headers "Accept-Content" from client.
    • no extension or .php
      • Serialized PHP output
    • .json
      • json output
    • .raw / .txt
      • var_export output for debug
    • .xml
      • (partial) XML support. Not really that useful (sorry REST fans - patches are welcome!)
  • Semi self-describing
    • API lists valid versions and endpoints when invalid ones are used
  • Actions (server-side processing) only occurs via POST / PUT / DELETE requests

Developing features into the API is very simple.

  • API routing is done using a local fork of Respect\Rest Routing framework
    • Our local fork is modified to support clusterducks desired filesystem layout and simple HTTP exit codes
    • Respect\Rest functionality is otherwise unchanged
  • The api folder contains a versions directory

  • Each directory in the versions directory is named after an API version, and contains all the endpoint controllers for that version:

    api
└── versions
    └── v0.9.2
        └── endpoints
            ├── user.php
            └── users.php
  • Endpoints are accessed via https://panel.example.com/api/endpoint, for example, the users endpoint is located at https://panel.example.com/api/users and is called users.php
    • The endpoint file may be a simple alias to another endpoint. The users endpoint includes the user endpoint, for example.