SheepAPI Core ============= Get an auth token ----------------- A core auth token will provide access to all data resources for a :term:`flock`. .. code-block:: http $ http POST https://api.sheepcrm.com/api/v1/auth/ username=james@james-webster.co.uk password=password HTTP/1.1 403 FORBIDDEN { "error": "Unable to authenticate", "error_detail": "Username and Password do not match an account" } that's not the password... With correct credentials you should get an api key returned. .. code-block:: http HTTP/1.1 200 OK { "api_key": "7ba68f4c99" } Making an authenticated request ------------------------------- 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 .. code-block:: http $ http https://api.sheepcrm.com/api/v1/$FLOCK/ Authorization:"Bearer $API_KEY" HTTP/1.1 200 OK { "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", }, ... ] } List available databases (flocks) --------------------------------- A typical user will only be connected to a single database (:term:`flock`) but you can verify which flocks a user has permissions to access with the base ``/api/v1/`` call. .. code-block:: http http GET https://api.sheepcrm.com/api/v1/ Authorization:"Bearer $API_KEY" HTTP/1.1 200 OK { "flocks": [ { "identifier": "example", "name": "Sheep Example" }, { "identifier": "example-association", "name": "Example Association" }, { "identifier": "example-family", "name": "Example Family" }, ] } Create a resource ----------------- Resources are the data objects in Sheep. Each resource has it's own schema but the API calls to interact with resources are all the same. .. code-block:: http /api/v1/$FLOCK/{resource_type}/ http POST https://api.sheepcrm.com/api/v1/$FLOCK/person/ Authorization:"Bearer $API_KEY" first_name=Jim last_name=Lovell HTTP/1.1 201 CREATED { "bucket": "example", "data": { ... "first_name": "Jim", "last_name": "Lovell", ... }, "display_value": "an empty person", "links": [ ... ], "meta": { "created": "2020-02-12T13:47:45.695000", "last_updated": "2020-02-12T13:47:45.730000", "state": "updated" }, "resource": "person", "uri": "/example/person/5e44020149c3a85acee1ff9b/" } (empty fields removed for brevity) Get all resources of a given type --------------------------------- (Example limited to a page size of 1) .. code-block:: http http https://api.sheepcrm.com/api/v1/$FLOCK/person/\?page_size\=1 Authorization:"Bearer $API_KEY" HTTP/1.1 200 OK { "grand_total": 1216, "links": [ ... ], "page": 1, "page_size": 1, "pages": 1216, "results": [ { "_id": null, "bucket": "example", "created": "2015-01-05T20:44:34.447000", "data": { "abilities": [ "usher" ], "address_lines": [ "Studio 6" ], "adult": true, "anniversary": null, "authorised_pickup": null, "automatic_email_opt_out": null, "bio": null, "colour": null, "comms_permission": [ null, "sms", "telephone" ], "connections": [ null, "/example/organisation/54aaf9763078f80f3ed8ca0b/;Grant Recipient", "/example/organisation/54aaf97b3078f80f3ed8cad7/;Accreditation Contact", "/example/organisation/54aaf97b3078f80f3ed8cad7/;Garden Contact", "/example/organisation/54aaf97d3078f80f3ed8cb42/;Charity Fundraiser", "/example/organisation/54aaf9853078f80f3ed8cc9b/;Manager", "/example/person/5746cfa53078f87b2bc3e177/;shared interest" ], "country": "UK", "date_of_birth": null, "date_of_death": null, "deceased": null, "domain": null, "driving_licence": null, "editable_formatted_name": null, "editable_salutation": null, "email": [ "danied@home.com;home", "daniel.abbott@company.com;work__primary" ], "email_opt_out": false, "emergency_contact_details": null, "emergency_contact_details_2": null, "expertise": null, "external_ids": [ null ], "external_photo_url": null, "facebook_username": null, "first_name": "Daniel", "formatted_name": "Mr Daniel I Abbott", "gender": null, "geo": null, "gocardless_uid": null, "has_direct_debit_mandate": null, "hide_from_views": false, "initial": "I", "instagram_username": null, "interests": [ "Baking", "Volunteering" ], "iso_country": "GB", "job_title": "Administrator", "known_as": null, "language": null, "last_name": "Abbott", "legacy_uid": null, "linkedin_public_profile": null, "locality": "Witney", "mailchimp_last_sync": null, "mailsort_code": null, "member_original_join_date": null, "member_since": null, "name_suffix": null, "notes": null, "photo": "https://s3-eu-west-1.amazonaws.com/sheepcrm/example/person/54aaf7b23078f80d90d8ca7b/photo/54.jpg", "photo_required": null, "postal_code": "OX28 6AL", "region": "Oxfordshire", "salutation": "Mr Abbott", "school": null, "school_year": null, "school_year_modifier": null, "sen": null, "skype_username": null, "sortable_name": "abbott daniel i mr", "source": null, "stripe_last_sync": null, "stripe_uid": null, "tags": [ "bad-tag", "blue iguana", "donor", "family", "gift-aid", "mynewtag", "trustee", "🐑 member" ], "telephone": [ "01234 567 891;work", "01993 700 100;home" ], "test": null, "time_zone": null, "title": "Mr", "twitter_username": "example", "vend_uid": null, "website": "example.com", "xero_last_sync": null, "xero_uid": null }, "display_value": "Mr Daniel I Abbott", "id": "54aaf7b23078f80d90d8ca7b", "last_updated": "2020-02-24T00:09:05.852000", "links": [ ... ], "permissions": { ... }, "resource": "person", "state": "updated", "uri": "/example/person/54aaf7b23078f80d90d8ca7b/" } ], "total": 1216 } 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 Querying ^^^^^^^^ Each resource type can be queried using the same RESTful methods All people called James (``/{flock}/person/?first_name=james``) .. code-block:: http http https://api.sheepcrm.com/api/v1/$FLOCK/person/ Authorization:"Bearer $API_KEY" first_name==james All people called James Webster (``/{flock}/person/?first_name=james&last_name=webster&mode=AND``) .. code-block:: http http https://api.sheepcrm.com/api/v1/$FLOCK/person/ Authorization:"Bearer $API_KEY" 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``) .. code-block:: http http https://api.sheepcrm.com/api/v1/$FLOCK/person/ Authorization:"Bearer $API_KEY" first_name==james last_name==webster mode==OR Get a single resource record ---------------------------- e.g. uri = /example/person/5e44020149c3a85acee1ff9b/ This is the record that we created earlier with just the first name "Jim" and last name "Lovell". Most other data fields are empty ``null`` but some are generated by the system e.g. ``formatted_name`` .. code-block:: http http https://api.sheepcrm.com/api/v1/example/person/5e44020149c3a85acee1ff9b/ Authorization:"Bearer $API_KEY" HTTP/1.1 200 OK { "bucket": "example", "data": { "abilities": [ null ], "address_lines": [ null ], "adult": null, "anniversary": null, "authorised_pickup": null, "automatic_email_opt_out": null, "bio": null, "colour": null, "comms_permission": [ null ], "connections": [ null ], "country": null, "date_of_birth": null, "date_of_death": null, "deceased": null, "domain": null, "driving_licence": null, "editable_formatted_name": null, "editable_salutation": null, "email": [ null ], "email_opt_out": null, "emergency_contact_details": null, "emergency_contact_details_2": null, "expertise": null, "external_ids": [ null ], "external_photo_url": null, "facebook_username": null, "first_name": "Jim", "formatted_name": "Jim Lovell", "gender": null, "geo": null, "gocardless_uid": null, "has_direct_debit_mandate": null, "hide_from_views": false, "initial": null, "instagram_username": null, "interests": [ null ], "iso_country": null, "job_title": null, "known_as": null, "language": null, "last_name": "Lovell", "legacy_uid": null, "linkedin_public_profile": null, "locality": null, "mailchimp_last_sync": null, "mailsort_code": null, "member_original_join_date": null, "member_since": null, "name_suffix": null, "notes": null, "photo": null, "photo_required": null, "postal_code": null, "region": null, "salutation": "Sir", "school": null, "school_year": null, "school_year_modifier": null, "sen": null, "skype_username": null, "sortable_name": "lovell jim", "source": null, "stripe_last_sync": null, "stripe_uid": null, "tags": [ null ], "telephone": [ null ], "test": null, "time_zone": null, "title": null, "twitter_username": null, "vend_uid": null, "website": null, "xero_last_sync": null, "xero_uid": null }, "display_value": "Jim Lovell", "links": [ ... ], "meta": { "created": "2020-02-12T13:47:45.695000", "last_updated": "2020-02-12T13:47:45.813000", "state": "updated" }, "resource": "person", "uri": "/example/person/5e44020149c3a85acee1ff9b/" } Delete a single record ---------------------- you can recover the record using the UI but not currently via the API .. code-block:: http http DELETE https://api.sheepcrm.com/api/v1/example/person/5e44020149c3a85acee1ff9b/ Authorization:"Bearer $API_KEY" Update a record --------------- PUT a json packet, multiple fields allowed .. code-block:: http http PUT https://api.sheepcrm.com/api/v1/example/person/5e44020149c3a85acee1ff9b/ Authorization:"Bearer $API_KEY" first_name=Jim HTTP/1.1 200 OK { "first_name": "Jim", } Obfuscate a single record ------------------------- obfuscate a record to remove personal data but keep the record for auditing and reporting. .. code-block:: http http PUT https://api.sheepcrm.com/api/v1/example/person/5e44020149c3a85acee1ff9b/obfuscate/ Authorization:"Bearer $API_KEY" Get the display value for a single resource record --------------------------------------------------- .. code-block:: http http https://api.sheepcrm.com/api/v2/example/person/5e44020149c3a85acee1ff9b/display Authorization:"Bearer $API_KEY" HTTP/1.1 200 OK { "display_value": "Jim Lovell" } Get the avatar for a single resource record -------------------------------------------- .. code-block:: http http https://api.sheepcrm.com/api/v2/example/person/5e44020149c3a85acee1ff9b/avatar HTTP/1.1 200 OK +------------------------------+ | NOTE: binary data not shown | +------------------------------+