search

BSData / bsdata

BattleScribe data file hosting platform
http://battlescribedata.appspot.com/
94 stars 51 forks source link

Backend API specification #230

Open amis92 opened 5 years ago

amis92 commented 5 years ago

REST API definition:

https://github.com/BSData/bsdata/blob/41af6dbb415918dd9d1d074f23c36d3fc05919f4/src/main/java/org/battlescribedata/rest/RepoResource.java

Endpoints:

Verb URL description model
GET /{repo}/{filename} retrieves a file - be it an index, catalogue, game system or even a roster(?) - (file content)
GET /{repo} retrieves a JSON with repository details, including file list RepositoryVm.java
GET /feeds/{repo}.atom retrieves an Atom XML with the newsfeed content for the repo (latest update, currently); special case for all which is an aggregate of all other feeds. Atom XML
GET / retrieves a JSON with a list of available repositories RepositorySourceVm.java
POST /{repo}/{filename} Upload a file update, return confirmation JSON ResponseVm.java
POST /{repo}/{filename}/issue Report an issue, return confirmation JSON ResponseVm.java
amis92 commented 5 years ago

Out of those, non-critical endpoints include POST ones plus the atom feed.

Both the issue and atom are useful and see usage. The file update is almost never used.

The account from which the issues and file updates are created on GitHub: @BSDataAnon

amis92 commented 5 years ago

Endpoint usage

BattleScribe workflow

  1. App requests GET /repos endpoint when the user selects which repositories they want to "subscribe" to. Details of the subscribed repository are saved, including repositoryUrl and indexUrl endpoints.
  2. ~App requests GET /repos/{repo}/index.bsi file as provided by the RepositoryVm.indexUrl.~ App requests GET /repos/{repo} endpoint as provided by the RepositoryVm.repositoryUrl. If the request fails, it falls back to the index.bsi endpoint.
  3. ~App downloads files from URLs listed in index.bsi (those that are new/have higher revision), which currently is the GET /repos/{repo}/{filename} endpoint.~ App downloads files from RepositoryVm.repositoryFiles.fileUrl endpoint. It may or may not verify given file's revision before attempting download.

Website workflow

  1. Website main page requests the GET /repos list.
  2. Website "repo" page requests the RepositoryVm.repositoryUrl, currently GET /repos/{repo}.
    • repo page uses the POST endpoints for issue submission and file update submission