App should be easily built in both staging and production versions (major differences – Facebook App ID, Twitter App ID, endpoints).
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
To be determined.
There are 2 kinds of requests:
- unauthenticated (exclusively authentication-related endpoints, i.e. signup and login)
- authenticated by a token
Token can be obtained from the signup and login endpoints.
Requests are authenticated by setting a header:
'AUTHORIZATION': 'Token 1b4e2cc32b59a150b966c69a81880e170a42f3d3'
XMPP jid and password can be obtained from the endpoints returning My User Profile
response. This includes signup, login and /me/
endpoint.
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.
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
Certain endpoints support "revision-based" caching. Each change to the data they return will increment the revision by 1.
- me/artwork/ (
own
revision key) - me/favorites/ (
liked
revision key) - me/flagged/ (
flagged
revision key)
- 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
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.
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.
Status codes follow the standard convention.
HTTP 2xx
codes mean success.
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.
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.
The meta
field can store additional information important for whole app, not connected to particular resource.
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.
{
"meta": {
"signup_queue": {
"length": 4,
"place": 1
}
}
}
User is on the 1. place out of total 4 in queue.
{
"meta": {
"current_revisions": {
"liked": 10,
"own": 14,
"flagged": 11
}
}
}
Informs the client of the current revision numbers for these cached lists.
{
"meta": {
"updated_revisions": {
"liked": 12,
}
}
}
Informs the client of the current revision numbers updated due to THIS request.