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
)
- Exposed via
- Client API
- Exposed via
http(s)://storagenode/api/
- Available to panel
- Available for LAN clients
- Exposed via
- Legacy APIs for panel + client
- Exposed via
api.php
for panel
- Exposed via
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 dataHTTP DELETE
is used to remove objectsHTTP PUT
is to be used when creating an object with an IDHTTP POST
is used to create, replace or partially update an objectHTTP 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. usingPOST
onGET
method)
- Request for non-existing resource gives
- 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 aversions
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 athttps://panel.example.com/api/users
and is calledusers.php
- The endpoint file may be a simple alias to another endpoint. The
users
endpoint includes theuser
endpoint, for example.
- The endpoint file may be a simple alias to another endpoint. The