Provider Registry Web Services

From IHRIS Wiki
Revision as of 06:50, 17 October 2012 by Litlfred (talk | contribs)

These are web services cases for interacting with the provider registry. Please see the requirements and use cases


Web Service: PR-WS-1 Get Enterprise Professional ID

Fetches a HC Professional Enterprise ID for the professional specified by the professional ID parameter.

URL /ws/rest/v1/lookupbyid/epid
GET Parameters This contains only 2 parameters to identify the professional to return ${id_type} and ${id_number}

Where ${id-type} is one of the following:

  • NID - for a national identification number
  • APN - for an application number
  • PPN - for passport number
  • SSN - for social security number
and ${id_number} is the value of the associated id
GET Response
  • HTTP 200 - OK
  • The HTTP response body will contain the epid as plain text.
GET Error
  • HTTP 500 - Server Error - If the server encountered an error.
  • HTTP 400 - Bad Request - If the parameters are malformed.
GET Example /ws/rest/v1/lookupbyid/epid/?id_type=NID&id_number=1234567890

Other Resources: Use Case:PR-WS-1

Web Service: PR-WS-2 Query For Providers

Fetches a HC Professional Enterprise ID for the professional specified by the professional ID parameter.

URL /ws/rest/v2/query/providers
GET Parameters The following query parameters are allowed:
  • ${size} The maximum number number of EPIDs to return. Defaults to 50.
  • ${start} The starting offset for listing EPIDs. Defaults to 10.
  • The following search possible parameters will be "and"ed together
    • ${firstname} The provider's given name.
    • ${surname} The professional’s family name.
    • ${fosaid} The FOSAID for the facility a provider is posted to.
    • ${location} The code for the organizational unit under which the provider is posted.
    • ${category} The category (or cadre) of the provider.
    • ${type} The type of the provider 'PPS' for paid-public sector or 'CHW' for community health worker.
  • {format}The response format. One of 'hl7' or 'json'.
GET Response HTTP 200 - OK

The HTTP response body will contain a list of matching EIDSs as specified by the ${format} parameter:

  • If ${format}=json. Example:

{ 

    providers: {
      211312: {
        providerDetails : 'http://rhea-pr.ihris.org/webservices/details/provider?epid=211312',
        editProvider : 'http://rhea-pr.ihris.org/webservices/edit/provider?epid=211312',
        addPost : 'http://rhea-pr.ihris.org/webservices/add/post?epid=211312',
        queryPosts : 'http://rhea-pr.ihris.org/webservices/details/post?epid=211312',
        viewProvider : 'http://rhea-pr.ihris.org/providerregistry/view?id=person%7C23123123
      },
      131241241: {
        providerDetails : 'http://rhea-pr.ihris.org/webservices/details/provider?epid=131241241',
        editProvider : 'http://rhea-pr.ihris.org/webservices/edit/provider?epid=131241241',
        addPost : 'http://rhea-pr.ihris.org/webservices/add/post?epid=131241241',
        queryPosts : 'http://rhea-pr.ihris.org/webservices/details/post?epid=131241241',
        viewProvider : 'http://rhea-pr.ihris.org/providerregistry/view?id=person%7C31234
      },
    },
    total_size : 300,
    start: 10

}

  • ${format}=hl7. one per professional that matches the criteria, that contains the details of that professional. These messages will be contained within a RSS feed XML message. HL7v2 message specification and mapping:
GET Error
  • HTTP 500 - Server Error - If the server encountered an error.
  • HTTP 400 - Bad Request - If the parameters are malformed.
GET Example /ws/rest/v2/query/providers/?foasid=123&size=2&start=10
Notes Need to good way for limiting response length. See A collection: the list of bugs in the Launchpad API

Other Resources: Use Case:PR-WS-2

Web Service: PR-WS-3 Get Provider Detail

Fetches details of a provider by their EPID or other identification type.

URL /ws/rest/v2/details/provider
GET Parameters This contains the followng parameters to identify the provider whose details we shall return:

$epid. The providers EPID. Required.

  • ${format}The response format. One of 'json' or 'hl7'. Defaults to 'json',
GET Response
  • HTTP 200 - OK
  • For HL7 See QueryProfessionalRSS.xml
  • For JSON we return an associative array containing the provider's details as well as URLs related to various actions to perform on the provider:

{ 

 firstname: "Bill",
 surname:  "Smith",
 cadre: "Nurse",
 email: "bsmith@example.org",
 passport: "12312312",
 mutuelle: "123123444",
 csr:  "123123",
 nid:  "333",
 actions: {
   providerDetails: 'http://rhea-pr.ihris.org/webservices/details/provider?epid=211312',
   editProvider: 'http://rhea-pr.ihris.org/webservices/edit/provider?epid=211312',
   addPost: 'http://rhea-pr.ihris.org/webservices/add/post?epid=211312',
   queryPosts: 'http://rhea-pr.ihris.org/webservices/details/post?id=211312',
   viewProvider: 'http://rhea-pr.ihris.org/providerregistry/view?id=person%7C23123'
 }
}
GET Error
  • HTTP 500 - Server Error - If the server encountered an error.
  • HTTP 400 - Bad Request - If the parameters are malformed.

Other Resources: Use Case:PR-WS-3

Web Service: PR-WS-4 Query For Postings

Fetches details of a provider's postings by their EPID.

URL /ws/rest/v2/query/posts
GET Parameters This contains the following parameters to identify the provider whose details we shall return. The values of epid, foasid and orgunit are "and"ed together:
  • ${epid} The provider's EPID. Optional.
  • ${fosaid} The facility code. Optional.
  • ${orgunit} The code for the organizational unit for the posting. Optional
  • ${type} The type of the provider, one of PPS or CHW. Optional.
  • ${category} The category/cadre of the provider. Optional.
  • ${format}The response format. One of 'hl7' or 'json'
  • ${size} The maximum number number of IDs to return. Defaults to 50.
  • ${start} The starting offset for listing IDs. Defaults to 10.
GET Response
  • HTTP 200 - OK
  • If the format='hl7' .....
  • If the format='json' we return an array of associative arrays. The associative arrays have keys for the post attributes. For example:

{ 

 total_size : 2,
 start: 0,
 posts: {
   98798798 : {
      editPost: http://rhea-pr.ihris.org/webservices/edit/post?id=98798798',
      postDetails: http://rhea-pr.ihris.org/webservices/details/post?id=98798798'
   },
   9878799 : {
      editPost: http://rhea-pr.ihris.org/webservices/edit/post?id=98798799',
      postDetails: http://rhea-pr.ihris.org/webservices/details/post?id=98798799'
   }
  }
}
GET Error
  • HTTP 500 - Server Error - If the server encountered an error.
  • HTTP 400 - Bad Request - If the parameters are malformed.

Other Resources: Use Case:PR-WS-4

Retrieved from "https://wiki.ihris.org/mediawiki/index.php?title=Provider_Registry_Web_Services&oldid=46594"