This Document describes the Requierements on the WarpServer given by the AlbianWarp Client
The Server should provide a JSON based API with Endpoints for Every Ressource the Server has to handle.
These Resources are:
- User
- MailMessages
ChatMessagesCreatures- PRAY files
In addition to these Resource based Endpoints a Authentication Endpoint is needed
- Authentication
Every Ressource, beside the Authentication, must be stored into a SQL Database (preferably MySQL for Production and SQLite for Development)
Every Resource, must have a unique Identifier preferably an auto incrementing Int called id / <id> which can be used as the primary key on every table and to reference a single Item/Row of a certain resource API Wise.
A Permission System must not be implemented right away, but we should keep in mind that we might need it it in the Future. For further Information check out the Permission System Section of this Document.
Authentication should ne Token based for further Information check out the Authentication Section of this Document.
This Resource contains User informations and the Endpoints can be used to create Users and get the current authenticated User /user.
If you specify a <id> you can get User Information to a certain user, update and delte it. (sufficient power is needed) /user/<id>.
This endpoint should allow the following Methods for Creation and recieving Information on the Authenticated User:
- POST
- GET
To create a User you need to form a JSON request containing a valid Object based on this Schema with the POST Method.
Object:
{
"username": "username_as_string",
"password": "password_as_string",
"email": "email_address_as_string"
}To create a user no Authentication Token is needed and the Response on succesfully creatiung a User should be a Resource creation response.
If you call the /user Enpoint with the GET methode, the response contains the User information of the currently authenticated user, otherwise a Authentication requiered response should be returned
Json Object:
{
"id": id,
"username": "username"
}Statuscode: 200
This endpoint should allow the following Methods for recieving Information or Manipulating a User with the given id:
- GET
In the Future the PATCH Method should also be implemented to allow partial update in a given User (i.e. change the Password or Mail Address)
as well as the DELETE Method to allow Administrative Users to Delete a given User.
If you are authenticated and the User referenced by the given id exists the expected Response should be:
Json Object:
{
"id": id,
"username": "username"
}Statuscode: 200
The /message Endpoint allows an authenticated user to send a Messages to another Users and get an array of Message ID's each referencing a Message the authenticated user got.
The allowed Methods are:
- POST
- GET
The expected result of a GET request on the Message Endpoint is an array, that contains all Message ID's of Messages that are ment for the authenticated User.
If the User got no Messages, the returned array should be empty [].
An example Response could be:
Json Object:
[1,4,8,15,46,52,1337,9001]Statuscode: 200
The /message Enpoint accepts valid Message JSON Objects via POST such a Json Object consits of the UserID of an Existing User recipient_id an Subject subject and the Message message that should be sent.
An Example Object could be:
{
"recipient_id": 1337,
"subject": "Look at my Horse!",
"message": "look at my horse my horse is amazing give it a lick mmm - it tastes just like raisins.\nHave a stroke of its mane it turns into a plane and then it turns back again when you tug on its winkie!"
}The expected Response to succesfully sending a Message to another user should be a Resource creation response.
- Authentication requiered response
- If the recipient User does not exist, a Resource does not exist response is expected.
This endpoint is used to manipulate and recieve a messages, referenced by the given <id>.
This Endpoint Supports the following Methodes:
- GET
- DELETE
The GET Method returns the Message referenced by the <id> if the authenticated User is the recipient of it.
The Statuscode of a succesfull response is 200 and the JSON Object returned looks like this:
{
"sender_id": 42,
"sender_username": "Eifel",
"date_sent": "%Y%m%d%H%M%S",
"subject": "Blue",
"message": "Yo listen up here's a story\nAbout a little guy that lives in a blue world\nAnd all day and all night and everything he sees Is just blue!"
}- Authentication requiered response
- Resource does not exist response
- Insufficient Permission response
- If the Recipient of the requested Message is NOT the authenticated User!
The DELETE Method should delete the given Message if the Authenticated User is the Recipient of that Message, then a Resource deletion response should be send.
- Authentication requiered response
- Resource does not exist response
- Insufficient Permission response
- If the Recipient of the requested Message is NOT the authenticated User!
This endpoint is uses by the AlbianWarp Client to recieve a Message as a PRAY JSON Object.
This Endpoint Supports the following Methodes:
- GET
The GET Method returns the Message referenced by the <id> as a PRAY JSON Object if the authenticated User is the recipient of it.
The Statuscode of a succesfull response is 200 and the JSON Object returned looks like this:
{
"pray_base64": "BASE64_ENCODED_PRAYFILE"
}For Informations on how to build a valid PRAY file for this Response check here Build IMSG tag_block.
The PRAY Endpoint is special in a way that it kinda breaks with the RESTful design of the Server. It is used by the Albianwarp Client to send PRAY Files, created by the Game Engine, to the Server. This Endpoint accepts every incomming PRAY file, as long as the USer is authenticated, and has to parse it to understand what is suposed to happen.
This Endpoint only allows the POST Method.
The POST Method only accepts valid PRAY JSON Objects having a field named pray_base64 which contains a base64 encoded PRAY File.
Json Object:
{
"pray_base64": "BASE64_ENCODED_PRAYFILE"
}An incomming PRAY File could contain a tag_block of the Type OMSG(A Message sent by the game), in this case the Server must form a valid POST request on its own /message Endpoint to create that Message, or must otherwise store that Message in the Database.
More on thath Topic can be found in the working with PRAY Section of this Document.
--
--
The following responses are Standardized to follow the standard message Schema.
{
"message": "human readable description",
"id": <id>
}The successfull creation of a Resource returns a Statuscode of 201 (Created) and a Message following the Standard message Schema, where id is the unique <id> of the newly created entry referencing the new resource and the message field contains a human readable description like [RESOURCE TYPE] sucessfully created. where [RESOURCE TYPE] is i.e. "User", "Creature" or "Message".
The succesfull deletion of a Resource returns a Statuscode of 200 (OK) and a Message following the Standard message Schema, where id is the unique <id> of the deleted resource and the message field contains a human readable description like [RESOURCE TYPE] sucessfully deleted. where [RESOURCE TYPE] is i.e. "User", "Creature" or "Message".
If the action i.e. deletion or creation, could not be executed due to a missing authentication Token, a statuscode of 401 (Unauthorized) is returned alongside a Message, following the Standard message Schema, where the id is None, if no resource was in question, or the <id> of the requested resource. The message field contains a human readable description containing Authentication is requiered!
If an request could not be executed due to unsificient [rights](LINK TO USER SECTION REGARDING RIGHT MANAGEMENT) a statuscode of 403 (Forbidden) is returned alongside a Message, following the Standard message Schema, where the id is None, if no resource was in question, or the <id> of the requested resource. The message field contains a human readable description containing Insufficient Permission!
If a Resource already existed on creation i.e. a User with the Same username, the response statuscode 409 (Conflict) is returned, alongside a Message, following the Standard message Schema, where id is the unique <id> of the already existing resource and the message field contains a human readable description like [RESOURCE TYPE] already exists! where [RESOURCE TYPE] is i.e. "User"
If a requested Resource does not exist, a statuscode of 404 (Not Found) is returnd alongside a Message, following the Standard message Schema, where the id is None andhe message field contains a human readable description like [RESOURCE TYPE] not found! where [RESOURCE TYPE] is i.e. "User"
If a request does not meet certain criteria, like a given JSON Schema, a statuscode of 400 is returned alongside a Message, following the Standard message Schema, where the id is None and the message field contains a human readable description Bad request.
If a request could not be handled because of an unhandled Exception, the Standard return Message sould be a statuscode of 400 alongsude a Message, following the Standard message Schema, where the id is None and the message field contains a human readable description Internal Error.
The Authentication is Token Based and a valid AuthToken is generated by providing the correct Login Credentials, in a JSON Object, via POST on the /auth Endpoint.
The generation of an Authentication Token can be done by utilizing itsdangerous like in this example here: restful authentication with flask.
To recieve a valid AuthToken you send the following JSON Object, containing valid Login Credentials, via the POST Method to the Endpoint /auth:
i.E.
{
"username": "username",
"password": "P@ssw0rd"
}If the Login credentials where correct the response should be a Statuscode 200 and a AutToken JSON Object like this.
{
"AuthToken": "Valid AuthToken as ASCII String"
}In case the provided Login credentials did not match an existing User the Response would be a Insufficient Permission response (Statuscode 403 means "Forbidden").
Currently we dont make use of a grained Permission System but while implementing the API we should keep in Mind that we need a System to give and revoke Permissions for certain Actions on the API (like deleting a Resource that does not belong to you)
To avoid a complex System based on Groups/Tags or a hirarchical System, I suggest we expand the User Model by a small Integer field called power which stores the users power as a Int.
a posible granulation could be:
0Disabled User1Normal active User2Moderator User3Administrative User
I will extend this Section soon!