Seeking Clarification between REST Web Service and a API call

I am trying to explore some new possibilities outside of the normal day to day HL7 interfacing we do. I have only done 1 other Web Service interface but it was using a SOAP proxy wizard. Now I am tasked with trying to make a call to an external API 

https://npiregistry.cms.hhs.gov/api/

but I am a bit confused about how to go about doing it. Since they don't have a wsdl, this means it is a REST web service correct? or is it considered an API call? When I read the documentation it feels like it is more geared to building REST services/operations within Ensemble then connecting to one on the outside, am I missing something here.

Can someone help clarify this for me?

Is a API considered a Web Service? 

Am I missing something in the Documentation?

Thanks 

Scott

  • + 1
  • 1
  • 114
  • 6
  • 2

Answers

Hi Scott,

A "Web Service" is just a generic term for an electronic service that operates over HTTP.

SOAP and REST can both be considered as a web service. Whilst SOAP is a protocol, REST is just an architectural style that operates over HTTP.

The NPI registry API can also be considered a web service, but it's clearly not SOAP, and it doesn't really conform to a REST architecture style either.

In fact if you look at the demo page you realise that the API is actually just a simple HTML form submit handler where the form values are sent in the GET request, as you can see here it submits all of the form values even if we provide just one form value...

https://npiregistry.cms.hhs.gov/api/?number=&enumeration_type=&taxonomy_description=&first_name=&last_name=&organization_name=&address_purpose=&city=baltimore&state=&postal_code=&country_code=&limit=&skip=

You don't need to use a REST client library to work with this API, here is a simple command line demo just using the standard %Net library  - I had to create an empty SSL/TLS configuration in the management portal named npiregistry as this needs to work over SSL.

USER>set req=##class(%Net.HttpRequest).%New()                                    
USER>set req.SSLConfiguration="npiregistry"
USER>set sc=req.Get("https://npiregistry.cms.hhs.gov/api?city=baltimore&postal_code=212")
USER>set results={}.%FromJSON(req.HttpResponse.Data)
USER>write results.%Get("result_count")
10

For Ensemble you could just use the standard HTTP Outbound Adapter.

Sean,

I tried running through your example above. When I got to set results={} ,I got the following error. Does this mean I could not get a connection outside my firewall at the Hospital?

USER>set req=##class(%Net.HttpRequest).%New()
 USER>set req.SSLConfiguration="npiregistry"
 USER>set sc=req.Get("https://npiregistry.cms.hhs.gov/api?city=balimore&postal_code=212")
 USER>set results={}.%FromJSON(req.HttpResponse.Data)
 <THROW>%FromJSON+37^%Library.DynamicAbstractObject.1 *%Exception.General Premature end of data 12 Line 1 Offset 0
USER 2e1>write results.%Get("result_count")
 WRITE results.%Get("result_count")
^
<UNDEFINED>^%Library.DynamicAbstractObject.1 *results
USER 2e1>set results={}.%FromJSON(req.HttpResponse.Data)
 <THROW>%FromJSON+37^%Library.DynamicAbstractObject.1 *%Exception.General Premature end of data 12 Line 1 Offset 0

Thanks

Scott

Looks like there is no data.

Check the value of the sc variable after the get, it probably has an error message.

Did you set up a SSL/TLS configuration in the management portal first?

Yes I created a blank SSL/TLS confirguration called npireigstry just like you mentioned above.

I wrote out sc after executing the GET and got the following...

write sc0  [Š%<WRITE>zSend+199^%Net.HttpRequest.1 'USER #$^zSend+199^%Net.HttpRequest.1 +1 $^zGet+1^%Net.HttpRequest.1 +1X^@ +1$D^zExecute+15^%Studio.General.1 +1X^@ +1 D^runMtdLow+22^%SYS.BINDSRV +1 D^popFrame+199^%SYS.BINDSRV +1!D^ServerLoop+23^%SYS.BINDSRV +2!D^SuperConnect+34^%SYS.DBSRV +1"D^SuperServer+112^%SYS.SERVER +1

Any Idea on what this error could be?

Does this only work on certain Ensemble versions? I tried it on 2015.2.2 and was getting SYNTAX errors.

Try pasting the link in a browser.  I am able to hit that link from my local laptop, but if your ensemble servers are locked down to certain IP's and ports than that could be the issue

The older version of %Net needs to be set up more specifically, try this...

set req=##class(%Net.HttpRequest).%New()                                    
set req.SSLConfiguration="npiregistry"                                      
set req.Server="npiregistry.cms.hhs.gov"
set req.Https=1
set req.Port=443                                            
set sc=req.Get("/api?city=balimore&postal_code=212")
write req.HttpResponse.Data.Read(300000)

Sending requests to an external application or API is generally handled by an operation.  The beauty of selecting an operation to hit an external endpoint is the ease of use with the out of the box HTTP outbound adapter.  Depending on your implementation the out of the box HTTP outbound adapter may suffice, but that is not always the case say for example if you need to GET a security token prior to the POST of the actual request you would like to send.

Extending the REST operation would be my first step, but only after successful response messages are received from the external endpoint by using your favorite SOAP test tool such as POSTMAN or SOAPUI.  Once you have successful response messages from the external application or API you just have to mimic this request content within the code of the operation you would like to create.  I recommend reaching out to your sales engineer or referring to this link:  https://docs.intersystems.com/latest/csp/docbook/DocBook.UI.Page.cls?KEY...