devel_docs.md

Preface

App should be easily built in both staging and production versions (major differences – Facebook App ID, Twitter App ID, endpoints).

Staging server

Staging server addresses:

XMPP admin panel: http://chat.staging.example.bladepolska.com:9090

XMPP:             chat.staging.example.bladepolska.com
API endpoint:     http://api.staging.example.bladepolska.com
Login credentials for the Openfire Admin Console: admin/Vrio4Hz6

Production server

To be determined.

API authentication

There are 2 kinds of requests:

• unauthenticated (exclusively authentication-related endpoints, i.e. signup and login)
• authenticated by a token

Token authentication

Token can be obtained from the signup and login endpoints.

Requests are authenticated by setting a header:

'AUTHORIZATION': 'Token 1b4e2cc32b59a150b966c69a81880e170a42f3d3'

XMPP authentication

XMPP jid and password can be obtained from the endpoints returning My User Profile response. This includes signup, login and /me/ endpoint.

Security considerations

Under no circumstances store passwords in plain text or any other easy to overcome method.

On iOS: use Keychain.

On Android: similar apropriate method.

In production – SSL https is to be used for all communication.

Offline data store and synchronization

The client shall store and keep synchronized:

• flagged artwork ids (consult Revisions client-side cache chapter)
• liked artwork ids (consult Revisions client-side cache chapter)
• own artwork ids and their order (consult Revisions client-side cache chapter)
• friends list
• own profile

The client shall cache and update when necessary:

• artworks
• user profiles

Caching behaviour

Certain endpoints support "revision-based" caching. Each change to the data they return will increment the revision by 1.

Cached lists endpoints

• me/artwork/ (own revision key)
• me/favorites/ (liked revision key)
• me/flagged/ (flagged revision key)

Revision modifying endpoints

• artwork/(?P[0-9]+)/
  • POST
  • DELETE
• artwork/(?P[0-9]+)/forks/
  • POST
• artwork/(?P[0-9]+)/favorite/
  • POST
  • DELETE
• artwork/(?P[0-9]+)/flag/
  • POST
  • DELETE

Reading cached data

Endpoints return a list of current values for all revision keys (more on this in the "Metadata" chapter below).

Client should store the revision version from the last update and send them with a request to the cached list endpoint (have_revision query param).

If server's most recent revision number will be the same - it will respond with 304, and no content.

Modifying cached data

All the revision modifying endpoints will respond with the new revision number. If it's 1 bigger than the one client had stored before the update – it should not have to update the whole list, just update the fields it sent and store the new revision number.

API general design

Response status codes

Status codes follow the standard convention.

HTTP 2xx codes mean success.

Error codes

Reception of 403 Forbidden HTTP status code from API or "Unauthorized" message from XMPP server must result in immediate user logout.

In case of XMPP auth. error: try refreshing the JID and password from /me endpoint, relogin (all using modal spinner, block user interaction) and move to the signup screen if failed.

In case of 403: try relogin (using modal spinner, block user interaction) and move to the signup screen if failed.

HTTP 400 Bad Request usually means that client made a mistake while making the request.

Response envelope

Assume all responses will come in JSON format, enveloped as:

:::javascript
{
    "errors": {},
    "meta": {},
    "response": {}
}

Not all of the envelope fields must be present in a response.

Meta field

The meta field can store additional information important for whole app, not connected to particular resource.

Signup_queue

This metadata key contains information about the place in signup queue user occupies.

It is added to all responses to authorized requests until user is allowed access.

Both length and place keys will be present.

Example

{
    "meta": {
        "signup_queue": {
            "length": 4,
            "place": 1
        }
    }
}

User is on the 1. place out of total 4 in queue.

current_revisions

{
    "meta": {
        "current_revisions": {
            "liked": 10,
            "own": 14,
            "flagged": 11
        }
    }
}

Informs the client of the current revision numbers for these cached lists.

updated_revisions

{
    "meta": {
        "updated_revisions": {
            "liked": 12,
        }
    }
}

Informs the client of the current revision numbers updated due to THIS request.