The ORGA API is a RESTful API. It is used as back-end for the ORGA Web Client and other future applications working with the ORGA server.

This documentation defines the planned version 1.0.0 of the API. This is currently under development. Not all endpoints are already yet.

Endpoint	Method	Authorization	Purpose	Parameters	Fields
/	GET	Any	Welcome Message
/system	GET	Any
/system/user	GET	Any	Returns own user profile		id, username, name, email
/system/user	PATCH	Any	Partial edit own user profile		username, name, email
/system/user/<id>	GET	Any	Returns public user profile		id, username, name
/system/user/<id>	PUT	Admin	Edit user profile		username, name, email
/system/user/<id>	PATCH	Admin	Partially edit user profile		username, name, email
/system/user/<id>	DELETE	Admin	Removes the selected user

Endpoint	Method	Authorization	Purpose	Parameters	Fields
/messages/inbox	GET	Any	Returns a list of all received messages	scope, reference, show_deleted	id, caption, creator_id, receiver_id, created, updated, active

Endpoint	Method	Authorization	Purpose	Parameters	Fields
/	GET	Any	Welcome Message

Endpoint	Method	Authorization	Purpose	Parameters	Fields
/rulesets	GET	Any	Returns a list of available rulesets.		id, name, caption, description, active, default_order

Endpoint	Method	Authorization	Purpose	Parameters	Fields
/games	GET	Any	Returns a list of available games.		id, name, caption, description, active, default_order

The API depends on HTTPS. It provides user authentication and each user requires authorization to access certain endpoints defined by its role(s).

The user can log in using the endpoint /api/v1/system/user/login. The endpoint expects a basic HTTP authentication header with username and password. If those match a valid user in the database a token is generated and returned in the response with HTTP status 200. The response contains the base64 encoded username and token in the field 'auth'. If the given credentials are invalid the HTTP status 401 is returned. All other endpoints require a HTTP 'Authentication' header with the returned token. The token is stored for the given user in the database and will be invalidated 1 hour after the last API request. To log off the enpoint /api/v1/system/user/logoff is provided. It will return the HTTP status 401 on successfull loggoff.

The API defines the required user role for each endpoint and method. If the user is unauthorized the HTTP status 403 is returned. To give an user access to certain endpoints the user entry in /api/v1/system/user/ must be altered by an user with the admin role.

Many endpoints use the scope and reference parameters. Those are used to define how the ORGA server is used:

Scope	Reference	Remarks
User (1)	None or User ID	Normal user must pass no reference. Admins can perform requests on behalf of other users.
Player (2)	Player ID	All actions affect the game the player is assigned to (Each user has a Player ID for each game it has access to.) Will fail if the player does not match the user or the game is set inactive.
Character (4)	Character ID	All actions are performed as the selected character. A player can have more than one character. The game is selected based on the character. If the character is not controlled by the user (defined by its player entry) the request will fail.

Removing entries (using a DELETE request) is only allowed to admins and must be used with caution. There is no checking if any other entries still reference the entry that is deleted which will lead to inconsistencies in the data. The normal way to remove a certain entry is to set it to inactive, using a PATCH request with the body '{"active":false}'. This allows other entries to still reference the inactive entry and it can also be restored later. This also ensures that no information is lost and a history and rollback feature can be implemented later.