Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

This is a version one. Advance notification of breaking changes will be available in this document and will be sent by email to our developer mailing list.

Most API calls are using Token for verifying the request. You need to be an authorized user to obtain your API Token Key for more information and token request contact MSD Drugs Tool Administrators.

The base URL of the API is http://htools-tz-msd-drug-tool-api.dokku-1.codefortanzania.org/api to access and send your requests.

JSON Bodies

All POST, PUT, PATCH requests are JSON encoded and must have have content type of application/json, or the API will return a 415 Unsupported Media Type status code.

$ curl http://htools-tz-msd-drug-tool-api.dokku-1.codefortanzania.org/api/drugs/23 \
-H 'Content-Type: application/json' \
-d '{"name": "Zinc Sulphate",
      "form": "Tablet",
      "strength": "20 mg",
      "uom": "100 TABLETS",
      "price": "6,300",
	}'

HTTP Verbs

The API uses the standard HTTP verbs to indicate intent of a request:

• GET - To retrieve a resource or a collection of resources
• POST - To create a resource
• PATCH - To modify a resource
• PUT - To set a resource
• DELETE - To delete a resource

Limited HTTP Clients

If you are using an HTTP client that doesn't support PUT, PATCH or DELETE requests, send a POST request with an X-HTTP-Method-Override header specifying the desired verb.

$ curl http://htools-tz-msd-drug-tool-api.dokku-1.codefortanzania.org/api/drugs/23 \
-X POST \
-H "X-HTTP-Method-Override: DELETE"

All response bodies are JSON encoded.

A single resource is represented as a JSON object:

{
  "field1": "value",
  "field2": true,
  "field3": []
}

A collection of resources is represented as a JSON array of objects:

[
  {
    "field1": "value",
    "field2": true,
    "field3": []
  },
  {
    "field1": "another value",
    "field2": false,
    "field3": []
  }
]

Timestamps are in UTC and formatted as ISO8601.

Unset fields will be represented as a null instead of not being present. If the field is an array, it will be represented as an empty array - ie [].

HTTP Status Codes

We use HTTP status codes to indicate success or failure of a request.

Success codes:

• 200 OK - Request succeeded. Response included
• 201 Created - Resource created. URL to new resource in Location header
• 204 No Content - Request succeeded, but no response body

Error codes:

• 400 Bad Request - Could not parse request
• 401 Unauthorized - No authentication credentials provided or authentication failed
• 403 Forbidden - Authenticated user does not have access
• 404 Not Found - Resource not found
• 415 Unsupported Media Type - POST/PUT/PATCH request occurred without a application/json content type
• 422 Unprocessable Entry - A request to modify or create a resource failed due to a validation error
• 429 Too Many Requests - Request rejected due to rate limiting
• 500, 501, 502, 503, etc - An internal server error occured

Errors

All 400 series errors (400, 401, 403, etc) will be returned with a JSON object in the body and a application/json content type.

{
  "message": "Not Found"
}

500 series error codes (500, 501, 502, etc) do not return JSON bodies.

Validation Errors

In case of validation errors on a POST/PUT/PATCH request, a 422 Unprocessable Entry status code will be returned. The JSON response body will include an array of error messages.

{
  "message": "Validation Failed",
  "errors": [
    {
      "message": "Field is not valid"
    },
    {
      "message": "OtherField is already used"
    }
  ]
}

All responses from the API can limit fields to only the fields you need. Just pass in a columns query parameter with a comma separated list of fields you need

For example:

GET /api/drugs?columns=name,price

Would have the following response body:

[
  {
    "name": "Warfarin ",
    "price": "7,100"
  },
  {
    "name": "Vitamin B Complex",
    "price": "4,400"
  },
]

Requests for collections can return between 0 and 100 results, controlled using the limit and page query parameters. All end points are limited to 10 results by default.

GET /api/drugs?lmit=5&page=2

Not all endpoints support pagination. If they do, it will be mentioned in their documentation.

Some endpoints offer result sorting, triggered using the order_by query parameter. You can specify descending sort by postpending desc to a field. Not all fields can be sorted on. The endpoint documentation will list supported sort options.

GET /api/drugs?order_by=name,asc

Some endpoints offer result searching, triggered at the query parameter by entering the column name followed by the search query. Not all fields can be sorted on. The endpoint documentation will list supported sort options.

GET /api/drugs?name=paracetamol*

All requests are tracked as drugs.

Listing drugs

GET /api/drugs

Sample Request

GET /api/drugs?order_by=name,asc&limit=1

It's response

Status Code: 200 OK
Connection: Keep-Alive
Content-Length: 564
Content-Type: application/json; charset=utf-8


{
  "status": 200,
  "drugs": [
    {
      "id": 1,
      "name": "Acetylsalicylic ",
      "form": "Tablet",
      "strength": "300 mg",
      "uom": "1000 TABLETS",
      "price": "7,200",
      "created_at": null,
      "updated_at": null
    },
    {
      "id": 2,
      "name": "Adrenaline ",
      "form": "Injection",
      "strength": "1 mg/ml",
      "uom": "10 AMPOULES",
      "price": "8,900",
      "created_at": null,
      "updated_at": null
    }
  ]
}

Getting a single drug

GET /api/drugs/id

Sample Request

GET /api/drugs/11

It's response

Status Code: 200 OK
Connection: Keep-Alive
Content-Length: 272
Content-Type: application/json; charset=utf-8


{
    "drug":
    {
        "id": 11,
        "id": 1,
        "name": "Acetylsalicylic ",
        "form": "Tablet",
        "strength": "300 mg",
        "uom": "1000 TABLETS",
        "price": "7,200",
        "created_at": null,
        "updated_at": null
    }
}

Updating drug

PUT /api/drugs/id?api_token={YOUR_API_TOKEN_KEY}

Sample Request

PUT /api/drugs/11?api_token={YOUR_API_TOKEN_KEY}
Content-Type: application/json;


{
    "name":"Zinc Light",
    "form":"Liquid",
    "strength":"0.5 Litre",
    "uom":"2",
    "price":"4,200"
}

It's response

Status Code: 200 OK
Connection: Keep-Alive
Content-Length: 180
Content-Type: application/json; charset=utf-8


{
    "drug":
    {
        "id": 11,
        "name":"Zinc Light",
        "form":"Liquid",
        "strength":"0.5 Litre",
        "uom":"2",
        "price":"4,200"
        "created_at": "2017-08-16 07:54:34",
        "updated_at": "2017-08-16 11:54:18"
    }
}

Creating a new drug

POST /api/drugs?api_token={YOUR_API_TOKEN_KEY}

Sample Request

POST /api/drugs?api_token={YOUR_API_TOKEN_KEY}
Content-Type: application/json;


{
    "name":"Zinc Light",
    "form":"Liquid",
    "strength":"0.5 Litre",
    "uom":"2",
    "price":"4,200"
}

It's response

Status Code: 201 Created
Connection: Keep-Alive
Content-Length: 467
Content-Type: application/json; charset=utf-8


{
    "drug":
    {
        "name":"Zinc Light",
        "form":"Liquid",
        "strength":"0.5 Litre",
        "uom":"2",
        "price":"4,200"
        "updated_at": "2017-08-16 12:16:45",
        "created_at": "2017-08-16 12:16:45",
        "id": 12
    }
}

Removing drug

DELETE /api/drugs/id?api_token={YOUR_API_TOKEN_KEY}

Sample Request

DELETE /api/drugs/11?api_token={YOUR_API_TOKEN_KEY}

It's response

Status Code: 200 OK
Connection: Keep-Alive
Content-Length: 643
Content-Type: application/json; charset=utf-8


{
  
}

Drug buying price

GET /api/drugs?name={name*}&buyin_price={price}

Sample Request

GET /api/drugs?name=zin*&buying_price=7000

It's response

Status Code: 200 OK
Connection: Keep-Alive
Content-Length: 272
Content-Type: application/json; charset=utf-8


{
  "status": 200,
  "drug": {
    "id": 215,
    "name": "Zinc Sulphate",
    "form": "Tablet",
    "strength": "20 mg",
    "uom": "100 TABLETS",
    "price": "6,300",
    "created_at": null,
    "updated_at": null
  },
  "price_check": {
    "buying_price_status": "above",
    "extra_amount": 700
  }
}