.. SheepCRM documentation master file, created by sphinx-quickstart on Tue Feb 11 17:37:57 2020. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. SheepAPI Documentation ====================== .. toctree:: :maxdepth: 1 :caption: Contents: /self-service/index /public/index /core/index /messaging/index /search/index /oauth /policies/index /solution-catalog/index /release_notes/index SheepAPI is the platform that supports sheepCRM, sheepTeams and sheepApp and the many partners that connect to Sheep data. The API is divided into two parts: the core system API and the self-service API. For apps wanting to provide an interface for a single contact the self service API will be of most use. The core API gives access to all data. Discord ======= We are experimenting with a Discord chat server to help our users. Join and say hello: https://discord.gg/GE8g88Ktds New API Documentation ===================== These documents are being replaced with OpenAPI documentation at https://sls-api.sheepcrm.com/.well-known/docs.html If there are contradictions please let us know and assume the newer OpenAPI documents are correct. Getting started =============== You need to have already registered for a Sheep database and have an active user account. We'll use the wonderful `httpie `_ http client in this document. See their site for installation instructions for your platform. Sheep APIs follow the RESTful design model wherever possible. HTTP verbs should be expected to work on all resources unless otherwise documented. We recommend testing API calls using httpie before implementing in code. If you need to submit a bug report please provide a working (failing) httpie example. We recommend `httpie` and the syntax is cleaner and generally simpler to read. If you are a `cURL` fan or can't install `httpie` we recommend the `Everything cURL `_ book for tips on using `cURL`. The examples will frequently refer to $FLOCK in the URL. You should replace this with the database that you want to work with. On a Mac use ``export FLOCK=example`` (replacing example...) then most URL examples can be copied directly. Check Sheep is up ----------------- and check that your environment is working properly. .. code-block:: http http https://api.sheepcrm.com/api/v1/ping/ HTTP/1.1 200 OK { "message": "pong" } Checking your permissions ------------------------- Once you have successfully 'pinged' the API try an authenticated call. To do this you will need to set two environment variables or replace the tokens with your actual values in the example. (If you don't have an API key you can set your own by logging into SheepCRM then navigate to the Profile settings or see `Get an auth token` in these docs.). .. code-block:: http export FLOCK=example export API_KEY=my-secret-api-key http https://api.sheepcrm.com/api/v1/$FLOCK/ Authorization:"Bearer $API_KEY" .. code-block:: http http https://api.sheepcrm.com/api/v1/example/ Authorization:"Bearer my-secret-api-key" You are expecting a HTTP 200 response with a list of resources as your response. A 403 FORBIDDEN response indicates a problem with your API key or your permissions. HTTP Access codes ----------------- .. glossary:: 200 OK 201 create 403 forbidden - you do not have access to this resource (check you Auth/API Key) 404 not found (also returned on bad user credentials) 409 conflict (auth and structure ok but a problem with the data values) 4xx client error 5xx Sheep error up HTTP Verbs ---------- .. glossary:: GET Read PUT Update POST Create. Note: The system tries to stop accidental duplicates so a POST will check before creating. If you need to create a record which the system may think is a dupe then either send more data (to show uniqueness) or create with unique data and then update. (legacy_uid is a good field that you can control). DELETE Delete Terminology ----------- .. glossary:: api_key The bearer token provided by the auth call. The bearer token must be supplied as a header for all authenticated calls. flock The client identifier/database also known as a ``bucket`` resource_type These are the data type / tables / models used by Sheep. ``person, organisation, booking, ticket, payment`` are all examples of resource types. resource A single record of a given resource type primary resources person, organisation, booking, group secondary resources e.g. payment, ticket, membership These are records which attach to primary resources sheep uri Sheep URIs are used extensively to refer to resources they are comprised of ``/$FLOCK/{resource_type}/{uid}/`` slugified uri A Sheep URI as a string ``$FLOCK-{resource_type}-{uid}`` API Throttling -------------- We reserves the right to modify the rate limits at any time. For the up-to-date information on rate limits, you can review the HTTP response headers returned from rate-limited endpoints. If you receive a rate limit-related response header, it will include numeric information detailing your status. :x-rate-limit-limit: The maximum number of requests available in the current time frame per hour and per minute :x-rate-limit-remaining: The number of remaining requests in the current time frame. :x-rate-limit-reset: The number of seconds (approximately) until the limit resets The rate limit string: e.g. `[ '40, 400;window=60, 1000;window=3600' ]` 40 calls remaining, the minute window limit is 400, the hour window is 1000