API Usecases

Blog post explaining how to access our API http://thesentinelproject.org/learn-how-to-access-the-sentinel-project-open-data-with-our-apis/

This document outlines the requirements for the ThreatWiki API - to be used by javascript developers to access data stored with each SP SOC.

General principles Basic REST design, using 4 verbs: POST, GET, PUT, DELETE

As of now, DELETE was deactivated since we don’t want to delete data, only archive it

Items in bold are given full public access (so you can test it on http://threatwiki.thesentinelproject.org/api/XYZ ) Items that are not in bold are limited for authenticated users of the platform

Note about Dates

Date format is milliseconds since 1970/01/01

Date "after" means after 0:0:0:0 of that date, hence including it

Date "before" means before 23:59:59:59 of that date, hence including it

Use this website to convert your date format into the UTC milliseconds format http://www.timestampconvert.com/

###Datapoint API

GET /api/datapoint

• Get all datapoints

GET /api/datapoint/:id

• Get the datapoint that corresponds to that :id

GET /api/datapoint/date/:date

• Get all datapoints that have a creation date on this specific :date

GET /api/datapoint/date/after/:date

• Get a list of all datapoints created after this :date (inclusive)

GET /api/datapoint/date/before/

• Get a list of all datapoints created before this :date (inclusive)

GET /api/datapoint/date/range/:date1/:date2

• Get a list of all datapoints created in the range between :date1 and :date2 (inclusive)

GET /api/datapoint/user/:username

• Get all datapoints created by :username (that corresponds to their @sentinelproject.org email address)

GET /api/datapoint/location/:Location

• Get all datapoints present at specific :location (location name)

GET /api/datapoint/tag/:taglist_id

• Under the URL format /api/datapoint/tag/idnumberone,idnumbertwo,idnumberthree Get all datapoints that are linked with that list of tag IDs (a tag can only be associated with 1 SOC, so all datapoints retrieved will be unique to that SOC linked with that tag). If multiple tags specified, the datapoints return must contain all tags specified in argument

GET /api/datapoint/soc/:soc

• Get all datapoints linked with that Situation of Concern (SOC)

POST /api/datapoint

• Create a new datapoint

PUT /api/datapoint/:id

• Update datapoint at id :id

PUT api/datapoint/:id/archive

• Set value for archive field (boolean). Archive true will hide the element from all GET calls, but it's still present in the database

###Situation of Concerns (SOC)

GET /api/soc

• Get a list of all SOCs

GET /api/soc/:id

• Get the SOC with that :id

GET /api/soc/date/:date

• Get all SOCs created on a specific :date

GET /api/soc/date/after/:date

• Get all SOCs created after a specific :date (inclusive)

GET /api/soc/date/before/:date

• Get all SOCs created before a specific :date (inclusive)

GET /api/soc/date/range/:date1/:date2

• Get all SOCs created in the range :date1 to :date 2 (inclusive)

GET /api/soc/title/:title

• Get the only SOC with that specific :title

GET /api/soc/user/:username

• Get all SOCs created by a user (using sentinel project’s email address)

POST /api/soc

• Create a new SOC

PUT /api/soc/:id

• Update SOC with that specific :id

PUT api/soc/:id/archive

• Set value for archive field (boolean). Archive true will hide the SOC from all GET calls but it's still present in the database.

###Tag API

GET /api/tag

• Get all tags

GET /api/tag/:idlist

• Get list of tags, under the URL format /api/tag/idnumberone,idnumbertwo,idnumberthree

GET /api/tag/soc/:soc

• Get all the tags linked with a specific :soc title

GET /api/tag/title/:title

• Get all the tags with that :title (title is not unique, there could be a tag “demonstration” linked with SOC Kenya and another tag “demonstration” with SOC Iran)

GET /api/tag/datapoint/:datapointid

• Get all the tags linked with a specific :datapointid

GET /api/tag/date/:date

• Get all the tags created on that :date

GET /api/tag/date/after/:date

• Get all the tags created after that :date (inclusive)

GET /api/tag/date/before/:date

• Get all the tags created before that :date (inclusive)

GET /api/tag/date/range/:date1/:date2

• Get all the tags created from :date1 to :date2 (inclusive)

GET /api/tag/user/:username

• Get all the tags created by that user’s sentinel email

POST /api/tag

• Create new tag

PUT /api/tag/:id

• Update tag :id

PUT api/tag/:id/archive

• Set value for archive field (boolean). Archive true will hide the tag from all GET calls, but it's still present in the database.