Connecting to OSCAR's REST API

Owned by Marc Dumontier
Last updated: Feb 06, 2020 by John Wilson
2 min read


Introduction

OSCAR exposes it's web services to authorized users only. Apps must be registered on the OSCAR it would like to integrate with and it's not the app that "logs in", it's the provider. The provider will login directly into OSCAR, which will generate a token for the app to make further calls.

The protocol implemented in OAUTH 1.0a (https://oauth.net/core/1.0a/)


Configuration


1) Enable the REST API for connecting apps. In the properties file add

ModuleNames=REST


2) Register the app with OSCAR through the Administration interface. Under "Integration" , select "REST Clients".

Choose "Add New", and enter a name and VALID URI for the application. The URI must be the base URL of your web application. 


3) Use the "Client Key" and "Client Secret" in your OAUTH initialization.



Sample Workflow

1) Client makes a REST call including proper "Authorization" header.  (for example: http://localhost:8080/oscar_15/ws/services/providerService/providers_json)


2) OSCAR will either return the results of the call (regular 200 HTTP status) or a 401 requiring the user to authorize with OSCAR first. Assuming we get the 401,


3) Client will initiate the OAUTH 1.0a flow by calling initiate (http://localhost:8080/oscar_15/ws/oauth/initiate). Make sure the client properly manages any cookies as well. This call will also include the callback URL to your application. This will get called when the OAUTH workflow is completed. This will return you a Request Token.


4) Client now redirects user to http://localhost:8080/oscar_15/ws/oauth/authorize?oauth_token=<request_token>. 


5) User authorizes with OSCAR





4) User is redirected to the Callback URL of your application (specified in the initiate, and must be within the URI of the registered application). The URL will have parameters for the oauth_token and oauth_verifier.


5) Client requests an access token from http://localhost:8080/oscar_15/ws/oauth/token


6) Client makes REST calls using Authorization header with access token.




Sample JSP Program



1) To use with minimal changes deploy to http://localhost:8080/provider_emailer and your OSCAR to http://localhost:8080/oscar_15

2) Enable REST, register the application using URI http://localhost:8080/provider_emailer

3) Copy the consumer key and secret to showProviders.jsp in the APP. The variables are near the top of the file.

4) Point your browser to http://localhost:8080/provider_emailer/