automed integration – API Endpoints

API Endpoints

To send requests to any automed API endpoints, append the base URL with the path for the method that will receive the request that you want to send. Here’s an example of the beginning of a (GET) call to a development API:

https://automed.io/api/v1.0/history

And, here’s the equivalent call to the production API:

https://automed.io/api/v1.0/history

These are all of the API endpoints:

As you read these definitions, realize that treatmentId, historyId, and inventoryId are placeholders for actual identifier values that you must supply when making the call to the endpoint.

GET /api/v1.0/treatments — Retrieve all treatments for the entire farm

GET /api/v1.0/treatments/:treatmentId — Retrieve a specific treatment

GET /api/v1.0/history — Retrieve all the entire history for a farm

GET /api/v1.0/history/:historyId — get a particular history item for a farm

GET /api/v1.0/inventory — get all inventory for a farm

GET /api/v1.0/inventory/:inventoryId — get a particular inventory item for a farm

POST /api/v1.0/inventory — create a new inventory item for a farm

PUT /api/v1.0/inventory/:inventoryId — update an existing inventory item for a farm

Query parameters

The GET /api/v1.0/treatments, GET /api/v1.0/history, GET /api/v1.0/inventory endpoints will accept these query parameters:

limit — how many items per page should the api return. Defaults to 30, if omitted.

skip — paging offset. Defaults to 0, if omitted. E.g. if we have limit of 30 and skip of 5, then the api will return 30 items starting at the 6th one.

sort — sorting property and order. defaults to id ASC , if omitted (sort by id in ascending order).

includeCounts — tells the api, to return total, skip and limit in the response body

Examples

In the remainder of this article, we provide a number of examples. First, we provide a composite example that includes use of a variable and each of the query parameters given above.

You can test this example and all of the examples below in your own terminal application. Note that all requests are authenticated with the API key of b700f580044f0ad813004f14d0ff0355, which belongs to [email protected] user.

In the code block below, we provide an API call that is run through the Curl utility. The resulting JSON response will contain history items that begin with the 11th item and end with the 20th item. It includes parameters to return the items in a descending sort according to the value of the createAt property, and also includes the counts.

curl -H 'Authorization: Bearer b700f580044f0ad813004f14d0ff0355' 
https://automed.io/api/v1.0/history?skip=10&limit=10&sort=createdAt%20DESC&includeCounts
The JSON response would be similar to this:
{
  "total": 91,
  "skip": 10,
  "limit": 10,
  "result": [
    {
      "amId": 70,
      "user": 279,
      "farm": 44,
      "mhDate": "2016-05-16T19:23:57.000Z",
      "mhEvent": "Added Bovilis MH",
      "id": 365,
      "createdAt": "2016-05-16T11:25:58.000Z",
      "updatedAt": "2016-05-16T11:25:58.000Z"
    },
    {
      "amId": 266,
      "user": 279,
      "farm": 44,
      "mhDate": "2016-05-11T10:56:24.000Z",
      "mhEvent": "Added Weight Calibration Test 1ml 10kg",
      "id": 360,
      "createdAt": "2016-05-11T03:12:41.000Z",
      "updatedAt": "2016-05-11T03:12:41.000Z"
    },
    {
      "amId": 255,
      "user": 279,
      "farm": 44,
      "mhDate": "2016-05-06T12:35:21.000Z",
      "mhEvent": "Added Calibration Test 3ml",
      "id": 359,
      "createdAt": "2016-05-06T02:39:57.000Z",
      "updatedAt": "2016-05-06T02:39:57.000Z"
    },
}

In each of the code blocks below, we provide an API call that is run through the Curl utility.

To retrieve all the treatments for a farm:

curl -i -H 'Authorization: Bearer b700f580044f0ad813004f14d0ff0355' https://automed.io/api/v1.0/treatments

Retrieve a treatment having an ID of 4425:

curl -i -H 'Authorization: Bearer b700f580044f0ad813004f14d0ff0355' https://automed.io/api/v1.0/treatments/4425

Retrieve the entire history for a farm:

curl -i -H 'Authorization: Bearer b700f580044f0ad813004f14d0ff0355' https://automed.io/api/v1.0/history

Retrieve a history item having an ID of 389:

curl -i -H 'Authorization: Bearer b700f580044f0ad813004f14d0ff0355' https://automed.io/api/v1.0/history/389

Retrieve the entire inventory for a farm:

curl -i -H 'Authorization: Bearer b700f580044f0ad813004f14d0ff0355' https://automed.io/api/v1.0/inventory

Retrieve a inventory item having an ID of 158:

curl -i -H 'Authorization: Bearer b700f580044f0ad813004f14d0ff0355' https://automed.io/api/v1.0/inventory/158

The examples below make use of one or more of these parameters:

Name Description Restrictions Data types
amId ref_treatment id (internally, it’s a reference to a row in ref_treatments table). Must refer to an existing treatment Integer
batchNo This is a number printed on the medication package, which is the batch it was made in String
expiry Expiry date of the medication – must not be in the past Must be in the future Web UTC datetime (https://en.wikipedia.org/wiki/ISO_8601)
farm farm id Cannot use a farm id other than your own Integer
user user id Cannot use a user id other than farm owner’s Integer
miQuantity How much of the medication is in stock (E.g. 5.3) String

The example below exhibits a call to the POST /inventory endpoint to add a new inventory item. The response body will contain the new inventory item.

curl -i -H 'Authorization: Bearer b700f580044f0ad813004f14d0ff0355' -H "Content-Type: application/json" -X POST -d '{"miQuantity": 100, "batchNo":1234, "user": 279, "farm": 44, "amId": 223, "expiry": "2016-07-22T09:48:32.000Z"}' https://dev.automed.io/api/v1.0/inventory

NOTE: The API will return an error if any of these conditions are not met:

  • the user and farm must match with the authenticated user (having the API key = b700f580044f0ad813004f14d0ff0355)
  • the amID must exist in this automed account
  • the expiration date must not be in the past

This next example call the PUT /inventory to update the inventory item having an ID of 158. The response body will contain updated contents of the inventory item.

curl -i -H 'Authorization: Bearer b700f580044f0ad813004f14d0ff0355' -H "Content-Type: application/json" -X PUT -d '{"miQuantity": 200, "batchNo":1234, "user": 279, "farm": 44, "amId": 223, "expiry": "2016-07-22T09:48:32.730Z"}' https://dev.automed.io/api/v1.0/inventory/158

NOTE: The API will return an error if any of these conditions are not met:

  • the user and farm must match with the authenticated user (having the API key = b700f580044f0ad813004f14d0ff0355)
  • the amID must exist in this automed account
  • the expiration date must not be in the past

Python Examples

To use the examples below, you will need to be running Python2 or Python3  and link to the requests library (http://docs.python-requests.org/en/master/)

import requests
import json
from pprint import pprint
from datetime import datetime

class AutomedClient:
    ''' This class is a simple abstraction on top of Automed's RESTful HTTP API

    This class is a simple abstraction on top of Automed's RESTful HTTP API
        meant to illustrate the different interactions.
    
    '''
    def __init__(self, api_token):
        self.api_base = 'https://automed.io/api/v1.0'
        self.api_token = api_token

    def get_treatments(self, limit=30, skip=0, include_counts=False, sort_prop='id', sort_order='ASC'):
        sort = '{}%20{}'.format(sort_prop, sort_order)
        url = '{base}/treatments?limit={limit}&skip={skip}&sort={sort}'.format(base=self.api_base, limit=limit, skip=skip, sort=sort)
        if include_counts:
            url += '&includeCounts'
        r = requests.get(url, headers={'Authorization': 'Bearer {}'.format(self.api_token)})
        return r.json()

    def get_treatment(self, id_):
        url = '{}/treatments/{}'.format(self.api_base, id_)
        r = requests.get(url, headers={'Authorization': 'Bearer {}'.format(self.api_token)})
        return r.json()

    def get_history(self, limit=30, skip=0, include_counts=False, sort_prop='id', sort_order='ASC'):
        sort = '{}%20{}'.format(sort_prop, sort_order)
        url = '{base}/history?limit={limit}&skip={skip}&sort={sort}'.format(base=self.api_base, limit=limit, skip=skip, sort=sort)
        if include_counts:
            url += '&includeCounts'
        r = requests.get(url, headers={'Authorization': 'Bearer {}'.format(self.api_token)})
        return r.json()

    def get_history_item(self, id_):
        url = '{}/history/{}'.format(self.api_base, id_)
        r = requests.get(url, headers={'Authorization': 'Bearer {}'.format(self.api_token)})
        return r.json()

    def get_inventory(self, limit=30, skip=0, include_counts=False, sort_prop='id', sort_order='ASC'):
        sort = '{}%20{}'.format(sort_prop, sort_order)
        url = '{base}/inventory?limit={limit}&skip={skip}&sort={sort}'.format(base=self.api_base, limit=limit, skip=skip, sort=sort)
        if include_counts:
            url += '&includeCounts'
        r = requests.get(url, headers={'Authorization': 'Bearer {}'.format(self.api_token)})
        return r.json()

    def get_inventory_item(self, id_):
        url = '{}/inventory/{}'.format(self.api_base, id_)
        r = requests.get(url, headers={'Authorization': 'Bearer {}'.format(self.api_token)})
        return r.json()

    def create_inventory_item(self, qty, batch_no, user, farm, am_id, expiry):
        url = '{}/inventory'.format(self.api_base)
        data = {
            "miQuantity": qty,
            "batchNo": batch_no,
            "user": user,
            "farm": farm,
            "amId": am_id,
            "expiry": expiry
        }
        r = requests.post(url, data=json.dumps(data), headers={'Authorization': 'Bearer {}'.format(self.api_token), 'Content-Type': 'application/json'})
        return r.json()

    def update_inventory_item(self, id_, qty, batch_no, user, farm, am_id, expiry):
        url = '{}/inventory/{}'.format(self.api_base, id_)
        data = {
            "miQuantity": qty,
            "batchNo": batch_no,
            "user": user,
            "farm": farm,
            "amId": am_id,
            "expiry": expiry
        }
        r = requests.put(url, data=json.dumps(data), headers={'Authorization': 'Bearer {}'.format(self.api_token), 'Content-Type': 'application/json'})
        return r.json()


# Initialize automed client
ac = AutomedClient(api_token='xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx')

# Get 3 first treatments
treatments = ac.get_treatments(limit=3, include_counts=True)
pprint(treatments)
'''Output:

{'limit': 3,
 'result': [{'amProduct': 'Bilosin 200 Tylosin Injection',
             'code': 'AUTOAU01',
             'createdAt': '2016-03-04T02:49:51.000Z',
             'email': '[email protected]',
             'id': 4376,
             'trBatchno': None,
             'trDate': '2016-03-04T00:00:00.000Z',
             'trDose': '1',
             'trReldate': None,
             'updatedAt': '2016-03-04T02:49:51.000Z',
             'vid': None,
             'weight': None},
            {'amProduct': 'Bilosin 200 Tylosin Injection',
             'code': 'AUTOAU01',
             'createdAt': '2016-03-04T02:58:07.000Z',
             'email': '[email protected]',
             'id': 4377,
             'trBatchno': None,
             'trDate': '2016-03-04T00:00:00.000Z',
             'trDose': '1',
             'trReldate': None,
             'updatedAt': '2016-03-04T02:58:07.000Z',
             'vid': None,
             'weight': None},
            {'amProduct': 'Bilosin 200 Tylosin Injection',
             'code': 'AUTOAU01',
             'createdAt': '2016-03-04T02:58:07.000Z',
             'email': '[email protected]',
             'id': 4378,
             'trBatchno': None,
             'trDate': '2016-03-04T00:00:00.000Z',
             'trDose': '1',
             'trReldate': None,
             'updatedAt': '2016-03-04T02:58:07.000Z',
             'vid': None,
             'weight': None}],
 'skip': 0,
 'total': 8252}
'''

# Get treatment with id 4378
treatment_4378 = ac.get_treatment(4378)
pprint(treatment_4378)
'''Output:

{'amProduct': 'Bilosin 200 Tylosin Injection',
 'code': 'AUTOAU01',
 'createdAt': '2016-03-04T02:58:07.000Z',
 'email': '[email protected]',
 'id': 4378,
 'trBatchno': None,
 'trDate': '2016-03-04T00:00:00.000Z',
 'trDose': '1',
 'trReldate': None,
 'updatedAt': '2016-03-04T02:58:07.000Z',
 'vid': None,
 'weight': None}
'''

# Get last 2 history items
history = ac.get_history(limit=2, include_counts=True, sort_prop='createdAt', sort_order='DESC')
pprint(history)
'''Output:

{'limit': 2,
 'result': [{'amId': 116,
             'createdAt': '2016-06-21T00:27:38.000Z',
             'farm': 44,
             'id': 386,
             'mhDate': '2016-06-21T06:31:32.000Z',
             'mhEvent': 'Added Bomectin Injection',
             'updatedAt': '2016-06-21T00:27:38.000Z',
             'user': 279},
            {'amId': 143,
             'createdAt': '2016-06-21T00:27:38.000Z',
             'farm': 44,
             'id': 387,
             'mhDate': '2016-06-21T06:25:01.000Z',
             'mhEvent': 'Added Tasvax 5-in-1',
             'updatedAt': '2016-06-21T00:27:38.000Z',
             'user': 279}],
 'skip': 0,
 'total': 91}
'''

# Get history item with id 387
history_387 = ac.get_history_item(387)
pprint(history_387)
'''Output:

{'amId': 143,
 'createdAt': '2016-06-21T00:27:38.000Z',
 'farm': 44,
 'id': 387,
 'mhDate': '2016-06-21T06:25:01.000Z',
 'mhEvent': 'Added Tasvax 5-in-1',
 'updatedAt': '2016-06-21T00:27:38.000Z',
 'user': 279}
'''


# Get 5 inventory items which are going to expire the soonest
inventory = ac.get_inventory(limit=5, include_counts=True, sort_prop='expiry', sort_order='ASC')
pprint(inventory)
'''Output:

{'limit': 5,
 'result': [{'amId': 254,
             'batchNo': '',
             'createdAt': '2016-04-19T12:06:30.000Z',
             'expiry': '2016-04-14T00:00:00.000Z',
             'farm': 44,
             'id': 135,
             'miQuantity': '100',
             'updatedAt': '2016-04-19T12:06:30.000Z',
             'user': 281},
            {'amId': 265,
             'batchNo': '5',
             'createdAt': '2016-04-24T22:37:57.000Z',
             'expiry': '2016-04-24T00:00:00.000Z',
             'farm': 44,
             'id': 138,
             'miQuantity': '2',
             'updatedAt': '2016-04-24T22:37:57.000Z',
             'user': 279},
            {'amId': 5,
             'batchNo': '88888',
             'createdAt': '2016-04-04T18:25:46.000Z',
             'expiry': '2016-04-28T00:00:00.000Z',
             'farm': 44,
             'id': 120,
             'miQuantity': '888',
             'updatedAt': '2016-04-04T18:25:46.000Z',
             'user': 281},
            {'amId': 227,
             'batchNo': '44444',
             'createdAt': '2016-04-04T16:38:49.000Z',
             'expiry': '2016-04-29T00:00:00.000Z',
             'farm': 44,
             'id': 119,
             'miQuantity': '44444',
             'updatedAt': '2016-04-04T16:38:49.000Z',
             'user': 281},
            {'amId': 254,
             'batchNo': '',
             'createdAt': '2016-04-19T12:09:37.000Z',
             'expiry': '2016-04-29T00:00:00.000Z',
             'farm': 44,
             'id': 134,
             'miQuantity': '100',
             'updatedAt': '2016-04-19T12:09:37.000Z',
             'user': 281}],
 'skip': 0,
 'total': 47}
'''


# Get inventory item with id 134
inventory_134 = ac.get_inventory_item(134)
pprint(inventory_134)

'''Output:

{'amId': 254,
 'batchNo': '',
 'createdAt': '2016-04-19T12:09:37.000Z',
 'expiry': '2016-04-29T00:00:00.000Z',
 'farm': 44,
 'id': 134,
 'miQuantity': '100',
 'updatedAt': '2016-04-19T12:09:37.000Z',
 'user': 281}
'''

# Create a new inventory item
new_item = ac.create_inventory_item(qty=5, batch_no=123, user=279, farm=44, am_id=254, expiry=datetime.now().strftime('%Y-%m-%dT%H:%M:%S.%fZ'))
pprint(new_item)
'''Output:

{'amId': 254,
 'batchNo': '123',
 'createdAt': '2016-07-28T21:38:32.070Z',
 'expiry': '2016-07-28T23:36:36.930Z',
 'farm': 44,
 'id': 174,
 'miQuantity': '5',
 'updatedAt': '2016-07-28T21:38:32.070Z',
 'user': 279}
'''

# Update an existing inventory item with id 134
updated_item = ac.update_inventory_item(id_=134, qty=5, batch_no=123, user=279, farm=44, am_id=254, expiry=datetime.now().strftime('%Y-%m-%dT%H:%M:%S.%fZ'))
pprint(new_item)
'''Output:

{'amId': 254,
 'batchNo': '123',
 'createdAt': '2016-07-28T21:43:45.415Z',
 'expiry': '2016-07-28T23:41:50.365Z',
 'farm': 44,
 'id': 176,
 'miQuantity': '5',
 'updatedAt': '2016-07-28T21:43:45.415Z',
 'user': 279}
'''

One Response

Leave a Reply

Your email address will not be published. Required fields are marked *