Specification v1

!!!DEPRECATED!!! This page describes the old v1 API which has since been replaced

This document describes Stockpile's latest version of the HTTP based interface. At the point of writing this is v1 which is available at the /v1/ endpoint.

Note: All endpoints herein are relative to the server's respective context path as declared in the application.yml.

Output Formats

Generally Stockpile supports both JSON and XML output for all of its endpoints. To retrieve a specific version of a resource, you can either append an Accept header which may either be set to application/json or application/xml (the text/xml media type is supported).

Alternatively you can append a file extension to most endpoints (e.g. /v1.json or /v1.xml).

GET /v1/

Retrieves runtime information of the backing server implementation.

{
  "api": {
    "state": "DEVELOPMENT",
    "version": 1
  },
  "name": "Stockpile",
  "vendor": "Torchmind",
  "version": "1.0.0-SNAPSHOT"
}

POST /v1/shutdown

Requests a graceful server shutdown.

POST /v1/blacklist

Checks whether a specified hostname or IP address has been blacklisted.

The hostname to check against can either be supplied by posting it as a raw request body or using form encoded data.

{
  "blacklisted": false,
  "hostname": "play.example.org"
}

GET /v1/login?username={username}&serverId={serverId}

Executes a login request which would usually be executed by the server directly and adds the resulting profile to the cache or, if a copy of the profile is already stored, updates the locally stored data.

Note: There is a special version of this endpoint which can be used to integrate with existing implementations. The response of this endpoint will replicate a perfect replica of the original session server response and can be accessed by appending the X-Forward header to the request.

{
  "cacheTimestamp": 1463609114.168,
  "identifier": "d71a5dac-4e71-443b-8158-4389c269e44d",
  "name": "HighLordAkkarin",
  "properties": [
    {
      "name": "textures",
      "signature": "...",
      "value": "..."
    }
  ]
}

GET /v1/name/{name}

Requests the associated UUID of a display name.

{
  "identifier": "d71a5dac-4e71-443b-8158-4389c269e44d"
}

POST /v1/name

Requests the associated UUID of a display name (the name is supplied as part of the request body).

{
  "identifier": "d71a5dac-4e71-443b-8158-4389c269e44d"
}

DELETE /v1/name/{name}

Purges a display name from the cache effectively causing the server to request a new version of the record next time it is requested.

DELETE /v1/name

Purges a display name from the cache effectively causing the server to request a new version of the record next time it is requested (the name is supplied as part of the request body).

GET /v1/profile/{name}

Requests a complete player profile (name can either be a display name or UUID).

{
  "cacheTimestamp": 1463609114.168,
  "identifier": "d71a5dac-4e71-443b-8158-4389c269e44d",
  "name": "HighLordAkkarin",
  "properties": [
    {
      "name": "textures",
      "signature": "...",
      "value": "..."
    }
  ]
}

POST /v1/profile

Requests a complete player profile (name can either by a display name or UUID; the name is supplied as part of the request body).

{
  "cacheTimestamp": 1463609114.168,
  "identifier": "d71a5dac-4e71-443b-8158-4389c269e44d",
  "name": "HighLordAkkarin",
  "properties": [
    {
      "name": "textures",
      "signature": "...",
      "value": "..."
    }
  ]
}

DELETE /v1/profile/{name}

Purges an entire profile from the cache effectively causing the server to request a new version of the record next time it is requested (the name can either be a display name or UUID).

DELETE /v1/profile

Purges an entire profile from the cache effectively causing the server to request a new version of the record next time it is requested (the name can either be a display name or UUID; the name is supplied as part of the request body).