Shepherd API Service

The Shepherd platform exposes a simple REST service over HTTPS which allows users to query the system to extract information that pertains to their accounts, this includes site and sensor information as well as being able to access the sensor data.

The service root URL is:

https://api.shepherd.fm:7075

The service uses HTTP Basic Authentication over SSL to ensure that usernames and passwords are secure. Therefore you need to encode your username password in the standard header to authenticate your request against the server. For example:

curl --user <USERNAME>:<PASSWORD> https://api.shepherd.fm:7075/v1/api/sites

The following documents the exposed endpoints

/v1/api/ping

This is an unsecured endpoint which allows clients to check they have the right server. It simply replies pong.

curl https://api.shepherd.fm:7075/v1/api/ping

/v1/api/sites

This is a secured endpoint which returns a JSON array of the sites which the authenticated user has access to

curl --user <USERNAME>:<PASSWORD> https://api.shepherd.fm:7075/v1/api/sites

Example output:

[
 {
    "user":{
       "id":1102,
       "email":"test@shprd.com",
       "telegramActivationToken":null,
       "telegramChatId":0000000,
       "mobile":"+4400000000",
       "landline":"",
       "firstName":"Test",
       "middleNames":null,
       "lastName":"User",
       "jobTitle":"",
       "companyName":"",
       "addressLine1":null,
       "addressLine2":null,
       "addressCity":null,
       "addressState":null,
       "addressPostcode":null,
       "addressCountry":null
    },
    "site":{
       "id":1049,
       "code":"TestRig",
       "name":"Shepherd Test Facility",
       "description":"Physical testing facility",
       "owner":"Shepherd Team",
       "timeZone":"UTC"
    },
    "source":{
       "id":0,
       "code":"*",
       "name":"Any Source",
       "description":"any source"
    },
    "perm":10351,
    "role":101,
    "action":"manage"
 }
]

/v1/api/site/{siteCode}

This is a secured endpoint which returns a JSON object describing the specified site provided the authenticated user has access to it

curl --user <USERNAME>:<PASSWORD> https://api.shepherd.fm:7075/v1/api/site/TestRig

The siteCode is found in the JSON response from the /v1/api/sites endpoint.

The produces the following types of result:

{ 
  "id":1049,
  "code":"TestRig",
  "name":"Shepherd Test Facility",
  "description":"Physical testing facility",
  "owner":"Shepherd Team",
  "timeZone":"Europe/London"
}

/v1/api/site/{siteCode}/sensors

This is a secured endpoint which returns a JSON array describing the sensors associated with the specified site provided the authenticated user has access to it

curl --user <USERNAME>:<PASSWORD> https://api.shepherd.fm:7075/v1/api/site/TestRig/sensors

which returns something like

[
 {
    "id":0,
    "type":"PowerDraw",
    "sourceCode":"LX",
    "siteCode":"TestRig",
    "name":"Current-Sensor",
    "displayName":"Current-Sensor",
    "criticalityLevel":"A",
    "units":null,
    "deviceSubType":null,
    "componentType":null,
    "location":null,
    "active":true,
    "criticalityLevelAsInt":1
 }
]

/v1/api/site/{siteCode}/sensor/{sensorName}/timeseries

This is a secured endpoint which returns a JSON object containing the sensor data for the specified sensor and site provided the authenticated user has access to it

curl --user <USERNAME>:<PASSWORD> https://api.shepherd.fm:7075/v1/api/site/TestRig/sensor/BoilerTemperature/timeseries

This produces results that contain the past 3 days and looks like:

{
   "type":"SCALAR",
   "title":"Power",
   "points":[
      {
         "timestamp":"2018-06-03 13:21:11",
         "uuid":"2406ff25-7845-435c-9605-ccbf1679ab0e",
         "value":2.41
      },
      {
         "timestamp":"2018-06-03 13:26:11",
         "uuid":"d6b89bdb-fe2c-4d7d-8e8e-875ea524b76f",
         "value":2.4
      },
      {
         "timestamp":"2018-06-03 13:31:10",
         "uuid":"4a32cf39-9947-4a6a-93a5-0bf697ace647",
         "value":2.41
      }
   ],
   "xaxis":"Time",
   "yaxis":"kW"
}

This endpoint also accepts a start and end URL request parameter in ISO-8601 format which allows the client to specify start and end times for the time series data, e.g.

curl --user <USERNAME>:<PASSWORD> https://api.shepherd.fm:7075/v1/api/site/TestRig/sensor/Current-Sensor/timeseries?start=2018-01-01T00:00:00Z&end=2018-06-06T15:27:52Z
  • user_manual/api.txt
  • Last modified: 2018/06/07 11:53
  • by admin