Skip to content

Latest commit

 

History

History
388 lines (346 loc) · 9.69 KB

Scenarios API.md

File metadata and controls

388 lines (346 loc) · 9.69 KB

Scenarios Data Model and REST API

Data models

The data models below are described in the mongoose notation for MongoDB data models.

Scenario

The scenario schema follows the immutable data type approach. Whenever something has to be updated (from a user perspective) the backend will create a copy of the current scenario with an incremented version number. All copies have the same UUID but different version numbers. All queries always return the newest copy (which can be determined using the version number).

{
  uuid        : { type: String, required: true  }, // same for all versions
  version     : { type: Number, required: true  }, // server-incremented
  title       : { type: String, required: true  }, // plain text
  summary     : { type: String, required: true  }, // plain text
  narrative   : { type: String, required: true  }, // markdown
  creator     : { type: String, required: true  }, // user uuid
  timestamp   : { type: Date, default: Date.now }, // set when created
  thumbnail   : { type: String                  }, // the thumbnail
  actors      : { type: [String]                }, // tags (comma-separated)
  sectors     : { type: [String]                }, // tags (comma-separated)
  devices     : { type: [String]                }, // tags (comma-separated)
  dataSources : { type: [String]                }, // uuids of data source type
}

Data source

{
  uuid        : { type: String, required: true }, // internal identifier
  href        : { type: Url,    required: true }, // link to original data source
  description : { type: String                 }  // markdown
}

Comments

TODO: integrate some "done" solution, e.g., disqus via https://www.npmjs.com/package/disqus-node

Data Transfer Objects (DTOs)

In this context a DTOs sole purpose is to define the schema of data transferred in various API methods between client and server. They are not used as database schemas and are not persisted 1:1.

Creare/Update Scenario

Used by clients when creating or updating a scenario resource. Included fields are identical to fields in Scenario schema but type is stripped down to fields that users are allowed to set when creating or updating a scenario resource.

{
  title       : { type: String, required: true  }, // plain text
  summary     : { type: String, required: true  }, // plain text
  narrative   : { type: String, required: true  }, // markdown
  actors      : { type: [String]                }, // tags (comma-separated)
  sectors     : { type: [String]                }, // tags (comma-separated)
  devices     : { type: [String]                }, // tags (comma-separated)
  dataSources : { type: [String]                }  // uuids of data source type
}

An image must be uploaded separatedly as form-data with the attribute thumbnail

Tag

Used for creating tag clouds or tag suggestions in the UI, e.g., for sectors, actors and devices of a scenario.

{
  tag   : { type: String, required: true }, // tag string, might contain multiple words with spaces, but is trimmed
  count : { type: Number, required: true }  // count of occurrences
}

Client REST API

Scenarios

All methods that (potentially) return more than one scenario support 'sortBy', 'sortDir', 'skip' and 'limit' parameters:

```sortBy``` Field of the scenario object to sort by, e.g., ```'title'``` or ```'timestamp'```.
```sortDir``` Direction to sort by: ```'asc'``` (ascending) or ```'desc'``` (descending)
```skip``` Paging: number of results to skip
```limit``` Paging: number of results to return (min: 1, max: 100)

List all scenarios

Description returns all latest versions of scenarios
Request GET /api/v1/scenarios
Response Body [Scenario]
Response Codes 200 OK - if successful

Full text search

Description do a full text search on all kinds of fields (google-style, whatever makes sense)
Request GET /api/v1/scenarios?q=keyword(s)
Response Body [Scenario]
Response Codes 200 OK - if successful

Fine-grained search

Description match fields on scenario schema, if multiple query parameters are given do a conjuction
Request GET /api/v1/scenarios?actors=politicians,people§ors=industry
GET /api/v1/scenarios?creator=uuid
Response Body [Scenario]
Response Codes 200 OK - if successful

Retrieval of a scenario (and it's old versions)

Description returns the most recent scenario version or an older version if query parameter v is given
Request GET /api/v1/scenarios/:id - returns the latest version
GET /api/v1/scenarios/:id?version=$VERSION - returns the version $VERSION GET /api/v1/scenarios/:id?version=all - returns all versions
Response Body Scenario | [Scenario]
Response Codes 200 OK - if successful
404 NOT FOUND - if not found

Creation of new scenario

Description creates a new scenario
Request POST /api/v1/scenarios
Request Body ScenarioUpdate
Response Body Scenario
Response Codes 201 CREATED - if successful, includes Location header of newly created resource
400 BAD REQUEST - if request is malformed (includes fields not allowed to be set by client, e.g. version, timestamp)
401 UNAUTHORIZED - need to be authenticated to create scenarios

Update of existing scenario

Description updates a scenario by creating a new scenario. in the backend this results in creating a new MongoDB document that has “backlinks” to it’s older versions
Request PUT /api/v1/scenarios/:id
Request Body ScenarioUpdate
Response Body Scenario
Response Codes 201 CREATED - if successful with Location header
400 BAD REQUEST - if request is malformed
401 UNAUTHORIZED - need to be authenticated to create scenarios
403 FORBIDDEN - if you’re not creator or admin
404 NOT FOUND - if not found

Deleting an existing scenario

Description deletes an existing scenario (the newest version if parameter v is not given or a specific version if v is given)
Request DELETE /api/v1/scenarios/:id
DELETE /api/v1/scenarios/:id?v=:version
Request Body ScenarioUpdate
Response Codes 204 NO CONTENT - if successfully deleted
401 UNAUTHORIZED - need to be authenticated to delete scenarios
403 FORBIDDEN - if you’re not creator or admin
404 NOT FOUND - if not found

Querying for tags (same for actors, sectors, devices)

Description returns tags for actors, sectors, devices, including popularity information (i.e. counts of how often a tag was used)
Request GET /actors
GET /devices
GET /sectors
Response Body [Tag], sorted by count
Response Codes 200 OK - with empty array if none found or like above

Retrieval similar/related scenarios from a scenario

Description returns the most similar/relevant scenarios for a input scenario. Similarity is calculated based on title, actors, devices.
Request GET /api/v1/scenarios/related/:id - returns similar scenarios
Response Body [Scenario]
Response Codes 200 OK - if successful
404 NOT FOUND - if not found

Get Disqus Statistics of Senario

Description returns a JSON object with scenario's statistics
Request GET /api/v1/scenarios/discus_statistics/:id - returns disqus statistics
Response Body {"likes": XYZ,"dislikes":XYZ,"comments":XYZ}
Response Codes 200 OK - if successful
404 NOT FOUND - if scenario not found 204 NO CONTENT - if disqus failed to deliver the stats