SkinEx Backend API

SkinEx Backend API.md

SkinEx Backend API

This is a documentation of SkinEx Backend API which should be implemented by yourself if you are hosting a special instance for your Minecraft server

Requiring authentication

Some endpoints may require authentication. If they do tokens are added to HTTP headers:

X-AccessToken: access_token
X-ClientToken: client_token

Servers

Get servers list

GET /servers

Note: tokens are sent if authentication is required in config for getting servers list

Response: JSON

{
  "recursiveable": true, // Is current backend able to look through all presented servers to load a skin?
  "servers": [{
    "name": "Server name", // Server name in servers list
    "id": "server_id",
    "flags": 7 // a bit mask representing user permissions
  }]
}

Errors: 401

User permissions

Permission	Bit code
Fetching other's skin	1
Override first permission	2
Deleting other's skins	4

Note: if first permission is NOT presented or second permission IS presented then tokens are always sent with skin requests

Get skin by nickname

GET /servers/:server_id/skins/:username

GET /servers/:server_id/skins/:username?recursive

If recursive fetching is supported and a user enabled it then empty query param recursive is added. Specified server should be treat as the top one of list of servers which should be searched for the skin

See the note under permissions table in previous section for token information

Response: PNG file

Errors: 401, 403, 404

Upload skin

PUT /servers/:server_id/skins

Note: must require authentication

Payload: simple form with one property file containing skin file

Response: empty response with 204 HTTP status

Errors: 401

Delete skin

DELETE /servers/:server_id/skins/:username

Note: Must require authentication

Response: empty response with 204 HTTP status

Errors: 401, 403

Authentication

All authentication requests are JSON-encoded and don't include tokens in HTTP headers

First login

POST /auth

Payload:

{
  "email": "steve@example.com",
  "password": "v3ryStr0nP@SS",
  "client_token": "client_token"
}

Response:

{
  "username": "Steve",
  "access_token": "access_token",
  "client_token": "client_token" // same as in payload
}

Errors: 401

Validating and refreshing tokens

POST /auth/refresh

Payload:

{
  "access_token": "access_token",
  "client_token": "client_token"
}

Response:

{
  "username": "Steve",
  "access_token": "access_token", // must be renewed
  "client_token": "client_token" // same as in payload
}

Errors: 401

Errors

All request can fail responding with HTTP error status. You can design error page as you want (actually no one should see it so just return empty response).

All acceptable error statuses are listed below. Other errors are acceptable, too, but they should never really happen if the request is sent by SkinEx and they don't have special messages in the app.

HTTP status code	Description	Condition
401 Unauthorized	Credentials are invalid	No tokens due to wrong configurations, expired tokens or wrong credentials in /auth
403 Forbidden	User is trying to get a resource which is not available for them	Fetching a skin or deleting other's skin without special permissions
404 Not Found	Requesting resource is not available	No skin found for specified nickname
500 Internal Server Error	Unexpected error happened	You did something wrong...