Sheep API intro.md

Sheep API introduction

Notes:

• replace {flock} with the client identifier
• 200 = OK
• 201 = create
• 4xx = Client screwed up
• 404 = not found (also returned on bad user credentials)
• 409 = conflict (auth and structure ok but a problem with the data values)
• 5xx = Sheep screwed up

curl defaults to GET the -d switch is an http POST

Check Sheep is up

curl https://api.sheepcrm.com/api/v1/ping/
{"message": "pong"}

Get an auth token

curl https://api.sheepcrm.com/api/v1/auth/ -d "[email protected]&password=password"
{"api_key": "7ba68f4c99"}

or

403 {"error_detail": "Username and Password do not match an account", "error": "Unable to authenticate"}

Get a list of resource types for the client account (& records numbers)

checks auth to the flock and provides a lookup for the different resource_types. resource_types are the Sheep name for what might normally be expected to be a database table or collection

curl https://api.sheepcrm.com/api/v1/{flock}/ -H "Authorization: Bearer {api token}"
{
  "resource_type": [
    {
      "count": 6,
      "name": "activity"
      "last_modified": "2017-03-28T18:57:47.637000",
    },
    {
      "count": 5,
      "name": "allocation"
      "last_modified": "2017-03-28T18:57:47.637000",
    },
    ...
    ]
}

or

409 {"error": "existing user account found"}
409 {"error": "existing person found without user account"}

Querying

Each resource type can be queried using the same RESTful methods

All records for a resource_type curl https://api.sheepcrm.com/api/v1/{flock}/{resource_type}/ -H "Authorization: Bearer {api token}"

All people (resource_type = person) curl https://api.sheepcrm.com/api/v1/{flock}/person/ -H "Authorization: Bearer {api token}"

All people called James ... /{flock}/person/?first_name=james

All people called James Webster ... /{flock}/person/?first_name=james&last_name=webster&mode=AND

All people called James or last name Webster ... /{flock}/person/?first_name=james&last_name=webster&mode=OR

Response payload

{
  "grand_total": 8,
  "links": [...],
  "results": [...],
  "page_size": 25,
  "page": 1,
  "formatted_results": [],
  "total": 8,
  "pages": 1
}

Results: (top level meta data)

"results": [
    {
      "resource": "person",
      "links": [...],
      "created": "2015-03-06T09:42:16.392000",
      "bucket": "example",
      "uri": "/example/person/54f97678a54d7568fa32b56a/",
      "id": "54f97678a54d7568fa32b56a",
      "state": "updated",
      "last_updated": "2015-05-19T09:07:55.858000",
      "data": {...},
      "display_value": "James Webster",
      "permissions": {...}  
    }
]

Result: Data packet (the field will depend on the schema of the resource)

"data": {
    "last_name": "Webster",
    "formatted_name": "James Webster",
    "photo": null,
    "hide_from_views": null,
    "telephone": [],
    "connections": [],
    "postal_code": null,
    "gender": "M",
    "first_name": "James",
    "title": "",
    "initial": null,
    "anniversary": null,
    "editable_formatted_name": null,
    "date_of_birth": null,
    "email": [
      null,
      "[email protected]"
    ],
    "job_title": null,
    "website": null,
    "sortable_name": "webster james",
    "tags": [],
    "date_of_death": null,
    "known_as": null,
    "geo": null,
    "address_lines": [
      null
    ],
    "language": null,
    "country": null,
    "region": null,
    "locality": null,
    "time_zone": null,
    "comms_permission": [],
    "expertise": null,
    "notes": null
}

Query logic

Append the field name with a modifier to use query logic. e.g. amount__gte=5 results where amount is 5 or more

• __and - and list
• __eq - exact
• __gt - greater than
• __gte - greater than or equals
• __lt - less than
• __lte - less than or equals
• __ne - not equal to
• __near - near
• __none - none of
• __or - or list
• __raw - raw
• __startswith - starts with
• __startswithi - starts with case insensitive

Schema definition for a resource

Each resource type in Sheep is defined by a schema. The schema defines the fields that are allowed, resource level permissions, filters and indexes. The most useful data is the list of fields and their types.

Field Types

• string
• date: datetime e.g. "2015-05-19T09:07:55.858000"
• s3image: url to an Sheep hosted S3 image
• s3file: url to an Sheep hosted S3 file
• int: integer
• number
• boolean
• tuple
• password: stored as plain text, obscured from UI (used for soft passwords)
• reference: uri to another Sheep resource
• time: deprecated
• link: deprecated
• resource: deprecated

curl https://api.sheepcrm.com/api/v1/{flock}/person/schema/ -H "Authorization: Bearer {api token}"

Get a single record

e.g. uri = /example/person/54f97678a54d7568fa32b56a/

curl https://api.sheepcrm.com/api/v1{uri} -H "Authorization: Bearer {api token}"
{
  "bucket": "example",
  "data": { ... },
  "display_value": "James Webster",
  "links": [...],      
  "meta": {
    "created": "2015-03-06T09:42:16.392000",
    "last_updated": "2015-05-19T09:07:55.858000",
    "state": "updated"
  },
  "resource": "person",
  "uri": "/example/person/54f97678a54d7568fa32b56a/"
}

Create a single record

The URI of the new record will be in the location header

curl https://api.sheepcrm.com/api/v1/{flock}/person/ -X POST -d '{"first_name":"Jim", "last_name":"Lovell", "email":"[email protected]"}' -H "Authorization: Bearer {api token}"
{
    "status": "ok",
}

Delete a single record

e.g. uri = /example/person/54f97678a54d7568fa32b56a/

you can recover the record using the UI but not currently via the API

curl https://api.sheepcrm.com/api/v1{uri} -x DELETE -H "Authorization: Bearer {api token}"

Update a record

e.g. uri = /example/person/54f97678a54d7568fa32b56a/

PUT a json packet, multiple fields allowed

curl https://api.sheepcrm.com/api/v1{uri} -X PUT -d '{"first_name":"Jim"}' -H "Authorization: Bearer {api token}"

Helper API calls

Check the membership for an email

curl https://api.sheepcrm.com/api/v1/{flock}/user/membership/?email={email} -H "Authorization: Bearer {api token}"

This call is useful for: a) checking if an email exists in your database (404 means the email doesn't match) b) checking membership status

Errors:

• 404: email not found
• 409: multiple contacts found for email

Note this call uses cached data for performance. If a real-time response is required (e.g. called immediately after a user has joined or cancelled then add realtime=Y as a param.

curl https://api.sheepcrm.com/api/v1/{flock}/user/membership/?email={email} -H "Authorization: Bearer {api token}"
{
  "active_memberships_for_display": ["Standard"], 
  "first_name": "James", 
  "last_name": "Webster", 
  "member_since": "2018-11-20T11:32:58.733000", 
  "member_till": "2019-11-20T00:00:00", 
  "member_till_plus_grace": "2019-12-20T00:00:00",
  "membership_numbers": ["10025"], 
  "membership_record_status": "active", 
  "primary_email": "[email protected]",
  "person": "/example/person/54f97678a54d7568fa32b56a/"
  }