Question
· Nov 30, 2018

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

Discussion (12)2
Log in or sign up to continue

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...

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

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.

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?

I think I am definately being blocked along the process somewhere. I tried the above commands as Sean mentioned with a proxy and without one, but I keep running into issues.

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

USER>set req=##class(%Net.HttpRequest).%New()
USER>set req.ProxyServer="10.127.20.41"
USER>set req.ProxyPort="8080"
USER>set req.SSLConfiguration="npiregistry"
USER>set req.Server="npiregistry.cms.hhs.gov"
USER>set req.Https=1
USER>set req.Port=443
USER>set sc=req.Get("/api?city=baltimore&postall_code=212")
USER>write req.HttpResponse.Data.Read(300000)
WRITE req.HttpResponse.Data.Read(300000)
^
<INVALID OREF>