Provider Registry Web Services

From IHRIS Wiki
The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

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

Web Service: PR-WS-5 Add a Provider

Add Provider Details

URL /ws/rest/v2/add/provider
GET Parameters The following webservice should accept the following parameters:
  • ${firstname} The first name of the provider. Required.
  • ${surname} The surname of the provider. Required.
  • ${nationality} The nationality of the provider coded according to ISO-3166-1 alpha-3. Required.
  • ${nid} The national id. Required.
  • ${passport} The passport number. Optional.
  • ${mutuelle} The mutuelle number. Optional.
  • ${csr} The CSR number. Optional.
  • ${respformat} Describes response format. Optional. Default is 'http', can also be 'json.'
GET Response HTTP 200 - OK
  • If ${repsformat} is 'http' the HTTP response body will contain the epid as plain text of the newly created provider.
  • If ${respformat} is 'json' it will contain a JSON object with the field 'epid' of the newly created provider as well as the URLs to access for further web-service actions to perform on the provider.

{ 

    epid: 211312,
    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.
GET Example /ws/rest/v2/add/provider/?firstname=Bill&surname=Smith&nationality=RW&nid=12312342

Other Resources: Use Case:PR-WS-5

Web Service: PR-WS-6 Edit a Provider

Edit Provider Details

URL /ws/rest/v2/edit/provider
GET Parameters The following webservice should accept the following parameters:
  • ${epid} The EPID of the provider. Required.
  • ${surname} The surname of the provider. Optional.
  • ${nationality} The nationality of the provider coded according to ISO-3166-1 alpha-3. Optional.
  • ${nid} The national id. Optional.
  • ${passport} The passport number. Optional.
  • ${mutuelle} The mutuelle number. Optional.
  • ${csr} The CSR number. Optional.
  • ${respformat} Describes response format. Optional. Default is 'http', can also be 'json.'
GET Response HTTP 200 - OK
  • If ${repsformat} is 'http' the HTTP response body will contain the epid as plain text.
  • If ${respformat} is 'json' it will contain a JSON object with the single field 'epid.'

further web-service actions to perform on the provider 

 Example:

{ 

    epid: 211312,
    actions: {
     providerDetails: 'http://rhea-pr.ihris.org/webservices/detials/provider/byid?id_num=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/query/posts?epid=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.
GET Example /ws/rest/v2/edit/provider/?provder=m&reg_body=2

Other Resources: Use Case:PR-WS-6

Web Service: PR-WS-7 Get Post Details

Show details of a provider's post

URL /ws/rest/v2/details/post
GET Parameters The following query parameters are allowed:
  • ${id} The id of the post
  • {format}The response format. One of 'json', ?'hl7'?
GET Response HTTP 200 - OK

Example: { 

    type: 'PPS',  #One of PPS or CHW
    category: 'NURSE', 
    fosaid: '012321',
    orgunit: '197834',
    startdate: '1992-12-22'  #year, month, day
    actions: {
       postDetails: 'http://rhea-pr.ihris.org/webservices/details/post?id=211312',
       editPost: 'http://rhea-pr.ihris.org/webservices/edit/post?id=211312'
    }
}
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/details/post/?id=12312321312
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-7

Web Service: PR-WS-8 Add a Post

Add Post Details

URL /ws/rest/v2/add/post
GET Parameters The following webservice should accept the following parameters:
  • ${type} The type of the post. One of 'PPS' for Paid-Public Sector or 'CHW' for Community Health Worker. Required.
  • ${category} The category/cadre of the providerm e.g. Nurse, Doctor. Required.
  • ${foasid} The facility code for this posting. Required.
  • ${orgunit} The organizational unit for this posting. Required.
  • ${startdate} The date the post is in effect. Format is 'YYYY-mm-dd'. Optional.
  • ${enddate} The date the post is no longer in effect. Format is 'YYYY-mm-dd'. Optional.
  • ${respformat} Describes response format. Optional. Default is 'http', can also be 'json.'
GET Response HTTP 200 - OK
  • If ${repsformat} is 'http' the HTTP response body will contain the id as plain text of the newly created posting
  • If ${respformat} is 'json' it will contain a JSON object with the field 'id' of the newly created post as well as the URLs to access for further web-service actions to perform on the post.

{ 

    id: 211312,
    actions: {
      editPost: 'http://rhea-pr.ihris.org/webservices/edit/post?id=992312',
      postDetails: 'http://rhea-pr.ihris.org/webservices/details/post?id=992312',
      viewPost: 'http://rhea-pr.ihris.org/providerregistry/post?id=post%7C992312',       
    }
}
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/add/post/?category=NURSE&type=PPS&fosaid=12312&orgunit=2133

Other Resources: Use Case:PR-WS-8

Web Service: PR-WS-9 Edit a Post

Edit details on existing post

URL /ws/rest/v2/edit/post
GET Parameters The following webservice should accept the following parameters:
  • ${type} The type of the post. One of 'PPS' for Paid-Public Sector or 'CHW' for Community Health Worker. Required.
  • ${category} The category/cadre of the providerm e.g. Nurse, Doctor. Optional.
  • ${foasid} The facility code for this posting. Optional.
  • ${orgunit} The organizational unit for this posting. Optional.
  • ${startdate} The date the post is in effect. Format is 'YYYY-mm-dd'. Optional.
  • ${enddate} The date the post is no longer in effect. Format is 'YYYY-mm-dd'. Optional.
  • ${respformat} Describes response format. Optional. Default is 'http', can also be 'json.'
GET Response HTTP 200 - OK
  • If ${repsformat} is 'http' the HTTP response body will contain the id as plain text of the editied posting
  • If ${respformat} is 'json' it will contain a JSON object with the field 'id' of the editedpost as well as the URLs to access for further web-service actions to perform on the post.

{ 

    id: 211312,
    actions: {
      editPost: 'http://rhea-pr.ihris.org/webservices/edit/post?id=992312',
      postDetails: 'http://rhea-pr.ihris.org/webservices/details/post?id=992312',
      viewPost: 'http://rhea-pr.ihris.org/providerregistry/post?id=post%7C992312',       
    }
}
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/edit/post/?category=NURSE&type=PPS&fosaid=12312&orgunit=2133

Other Resources: Use Case:PR-WS-9

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