AtoZ-API

From Book A Flight
Jump to navigation Jump to search

Overview

This is the overview starting page for the API.JSON infrastructure for AtoZ

The core of the system comprises:

  • /api-json/api.php
  • /api-json/Rest.inc.php
  • /api-json/dbConnect.inc.php

All calls to the system are calls to api.php, which handles presentation and uses the other two core files for the database interactions.

All API method calls follow the same generic process flow, as follows:

api.php simply instantiates a new API object ($api = new API) and then calls it's processApi() method The API method extends the "REST" class, and API's constructor is simply REST's constructor. ProcessAPI() checks to see if "method_exists" with the name of the API being called, and if so it executes this method. If no method exists it "responses" a 404 error. Every API method function must end with a call to response($data, $status) as this closes out the API call.

Step 1 - Rest->constructor:

  • Step 1a - Instantiate and start a new "ExecutionTime" object. This sets and stores two variable (startTimeCPU and startTimeClock)
  • Step 1b - execute $this->inputs(). This takes the POST or GET data and returns them as a key/value array. It also sets $this->_token if one of the parameters was "tok" and sets the value of $this->_func to the name of the API function that was invoked
  • Step 1c - if the call is NOT to "getToken" then we instantiate an AccessRights object and call it's checkToken method. This checks if the token in question has permission to access the API being invoked, and sets the EDL_Set that the API must be restricted to.
  • Step 1d - then we instantiate a Logging object and "start()" it with "token", "api method", "input list of medicines" and "EDL_Set" parameters. THIS ESTABLISHES WHICH MEDS ARE UNKNOWN TO US!!! This MUST NOT HAPPEN here


Step 2 - Invoke the actual API function (named to correspond with the api method used on the command line

  • Step 2a - Build up an array of the required output data as a "payload"
  • Step 2b - If any problems occur, call $this->response() with an error status and an error message
  • Step 2c - call $this->response(); with the $this->json(payload);


Step 3 - $this->response

  • Step 3a - Call setHeaders() to set the necessary API and CORS headers
  • Step 3b - Response.write the data payload
  • Step 3c - End the logging. This puts the payload into the logging response table for auditing purposes
  • Step 3d - Invoke $this->ExecutionTime->end() with a log_request_id and an output status. This calculates CPU and elapsed time durations since the start and records these in t_LOG_Request_Performance

.end.



Methods

Public methods are accessed as calls to https://www.atozofmedicines.com/app/api.json/ METHOD_NAME ? PARAMS

All public methods other than "getToken" need to be passed an access token as one of the input parameters. During the constructor to all other API methods the token is used to

  • force a login if the specified token has expired
  • check for permission to access the specific API in question (Checks for a record in AtoZ_API.t_User_API with permissible ValidFrom and ValidUntil range)
  • Sets $this->_EDL_Set from AtoZ_API.t_User_API.EDL_SET. This private variable is used to limit the available drugs that a client can access.

The following public methods exist in api.php

getToken

The getToken method is used to authenticate based on a username and password and the returned token is required for all other API calls

Inputs

  • "sys" (the system calling this - currently unused)
  • "usr" (the username to use)
  • "pwd" (the password to use)

Returns

Token : xxxxxxx

Example

http://atozofmeds.local/app/api.json/getToken?sys=web&usr=TESTING&pwd=API-TEST
{"token":"222628849519EF07"}

searchTrade

The searchTrade method is used to search for a medicine in the system.

This API does NOT honour the $this->_EDL_Set in returning results!

This API pulls ALL trades linked through the cross-map to AMIs, that have a NAPPI code != 0. It does NOT honour "dataset" restrictions.

Inputs

  • tok (a valid authentication token, with permission to access this API)
  • med (the name of the medicine to search for - code uses %med% wildcards in search)

Returns

ID, FullName

Example

http://atozofmeds.local/app/api.json/searchTrade?tok=222628849519EF07&med=panado
[{"ID":"109594","FullName":"Panado  \/  (CAP)"},
{"ID":"102512","FullName":"Panado 120 mg\/5 mL (SYR)"},
{"ID":"109591","FullName":"Panado 500 \/  (TAB)"},
{"ID":"107032","FullName":"Panado Childrens 125 mg\/  (MLT)"}]

Interactions

The method is used to search for interaction details for the medicines in the input list.

Inputs

  • tok (a valid authentication token, with permission to access this API)
  • lst (a pipe-delimited list of codes {nappi, NDC, etc} to include in the set
  • limit (Optional : a "Y", "N" field indicating if the results should be limited to the "DDU" set or not: defaults to "Y")
  • useKey – Optional, defaults to “Y”. Indicates if “lst” comprises a list of medicines that were identified by calling the AtoZ “searchTrade API (i.e. are a set of primary keys to the AtoZ database). Values are “Y” for yes, and “N” for no.
  • useCode – optional, defaults to “Y”. Indicates if “lst” comprises a list of medicines that are identified by a national coding system (e.g. a list of NAPPI codes, NDC codes etc.), Values are “Y” for yes, and “N” for no.

Returns

Token : xxxxxxx

Example

http://www.atozofmedicines.com/app/api.json/Interactions?tok=58807DD58D548695&lst=%7C110332%7C103851%7C108395%7C118351%7C102858&limit=N
{"DATA":[{"TradeA":"108395","MedicineA":"Cipla Warfarin","TradeB":"110332","MedicineB":"Zocor","severity":"unsafe.png",
   "Details":{
     "Detail1":{"Category":"Warning","Description":"Caution advised.","ReferenceID":"24675"},
     "Detail2":{"Category":"Advice","Description":"Individual response.","ReferenceID":"14706"},
     "Detail3":{"Category":"Advice","Description":"Substitute statin: atorvastatin, pravastatin.","ReferenceID":"24680"}
   }
 },
 {"TradeA":"102858","MedicineA":"Sandoz Omeprazole","TradeB":"108395","MedicineB":"Cipla Warfarin","severity":"unsafe.png",
   "Details":{
     "Detail1":{"Category":"Warning","Description":"Caution advised.","ReferenceID":"20168"},
     "Detail2":{"Category":"Monitor","Description":"INR\/PT levels closely if initiating, discontinuing or changing the dose of either drug.","ReferenceID":"20169"}
    }
 }],
 "MESSAGE":{"NoData":[["103851"],["118351"]]}}

Pregnancy

The method is used to return fields about Pregnancy risk for a given input set.

This method calls database stored procedure API_Preg with the medicine list, 'CHW-EN' as the translation set.

This method is limited by the client's EDL_Set restrictions.

The API_Preg stored procedure drives of Pregnancy.Dataset = 'DDU'

Inputs

  • token
  • lst - the pipe delimited list of medicines
  • useKey – Optional, defaults to “Y”. Indicates if “lst” comprises a list of medicines that were identified by calling the AtoZ “searchTrade API (i.e. are a set of primary keys to the AtoZ database). Values are “Y” for yes, and “N” for no.
  • useCode – optional, defaults to “Y”. Indicates if “lst” comprises a list of medicines that are identified by a national coding system (e.g. a list of NAPPI codes, NDC codes etc.), Values are “Y” for yes, and “N” for no.

Returns

"DriverID": "109594", "Name": "Panado", "Risk": "B", "Wording": "Caution. Not likely to harm the baby at usual doses. Use only if clearly needed.", "Icon": "caution.png", "ATC_Description": "Paracetamol", "ReferenceID": "9619"

Example

https://www.atozofmedicines.com/app/api.json/Pregnancy?tok=58807DD58D548695&type=Pregnancy&lst=109594%7C102038
{
   "DATA": [
       {
           "DriverID": "109594",
           "Name": "Panado",
           "Risk": "B",
           "Wording": "Caution. Not likely to harm the baby at usual doses. Use only if clearly needed.",
           "Icon": "caution.png",
           "ATC_Description": "Paracetamol",
           "ReferenceID": "9619"
       }
   ],
   "MESSAGE": {
       "NoData": [
           [
               "102038"
           ]
       ]
   }
}

Lactation

The method is used to

Inputs

Returns

Token : xxxxxxx

Example

http://atozofmeds.local/app/api.json/
{}

Porphyria

The method is used to

Inputs

Returns

Token : xxxxxxx

Example

http://atozofmeds.local/app/api.json/
{}

PIL (under development)

The method is used to

Inputs

Returns

Token : xxxxxxx

Example

http://atozofmeds.local/app/api.json/
{}

Reference

The method is used to return details for the references supporting a given API resultset.

Logic:

  • INTERACTIONS: SELECT Reference FROM Interaction_Details WHERE ID in (...)
  • PREGNANCY: SELECT Reference FROM Pregnancy_Details WHERE PregnancyID in (...)

Inputs

  • tok (a valid authentication token, with permission to access this API)
  • type (an indicator of the type of reference required - the "method" of the API call which gave rise to this reference request)
  • refid (the pipe-delimited set of ReferenceIDs from another API call, about which you wish details)

Returns

References : list of references in support of the specified details

Example

http://www.atozofmedicines.com/app/api.json/Reference?tok=58807DD58D548695&type=Interaction&refid=24675
{"DATA":[{   }],
 "MESSAGE":{"NoData":[]}}
Retrieved from "https://www.bookaflight.co.za/docs_online/index.php?title=AtoZ-API&oldid=1966"