REST API sample available on GitHub

[tweissin]

Hi,

To make it easier to integrate with the Context Service, a new sample has been uploaded to GitHub.  It provides an example of how you could write a REST API on top of the Java Context Service SDK.  This is useful for situations where you are using Javascript, .NET,  PHP or some other language and want to be able to perform create, update, and search (and in lab mode, delete) on Context Service objects.

You can find the webapp sample here: https://github.com/CiscoDevNet/context-service-sample-code/tree/master/Webapp_Sample_Project

The sample itself includes code to create two webapps:

• REST API webapp (rest.war) - exposes a REST API
• Management Connector webapp (management.war) - handles registration/deregistration and credentials changed listener

Note: The sample does not provide multi-tenancy (only one organization can be serviced by an instance of this webapp).

Handling Connection Data Changes

The sample CredentialsChangedListener is implemented in ManagementContextListener.java, and its logic is crucial to ensure your application's connection data is up to date.  Connection data is renewed every 270 days, so if you do not have a listener registered in your application to update it, the SDK will not initialize successfully if the connection data has expired.

You can find an example CredentialsChangedListener in the sample's ManagementContextListener class, which stores the connection data in a properties file in the local file system.  This is just an example, and it is recommended to store the connection data more securely and perhaps centrally (for instance, shared DB) in the case where your SDK webapp is hosted on multiple machines.

Note: Connection data should not be shared as it contains sensitive data.

Registration/Deregistration

The sample also demonstrates how to implement registration in your application.  First you call RegisteringApplication.createRegistrationRequest() to get a URL (see RegistrationService.java).  Your application should then direct the user to this URL (see app.js).  After an organization admin authenticates, the user's browser is redirected back to the callback URL.  In the sample, the RegistrationService saveConnectionData() method handles the callback to 1) save the connection data, and 2) initialize the management connector via ManagementConnector.init().

REST API

The sample provides create/retrieve/update/delete/search via REST.  (Custom fields and field sets to be used by context objects can be managed in the Cisco Spark Administration webapp by organization admins.)

For example, to create a new activity (pod), execute a POST request like this:

POST http://localhost:8080/rest
{
"type" : "pod",
"fieldsets": ["cisco.base.pod"],
"dataElements": [
        {
            "key": "Context_Notes",
            "value": "testing at 3:16"
        }
    ]
}

See the README.md file for more information.

Note: No authentication is provided on this REST API.  Depending on where the application is hosted, it is recommended that you include authentication (such as basic auth) in your implementation.

Deployment to Tomcat

Sample scripts make it easy to get started quickly.  The sample has a script prepareTomcats.sh that configures 2 instances of Tomcat, one to host the REST API, and the other to host the Management Connector webapp.

Note: The scripts are intended for Mac/Linux, but could be adapted for Windows.

Once the Tomcat instances are prepared properly, two scripts can be used to start and stop Tomcat (startTomcats.sh and stopTomcats.sh). The application can be accessed at the following URLs:

• http://localhost:8080/rest (for instance, http://localhost:8080/rest/status)
• http://localhost:8082/management

Tomcat logs can be found in:

• Webapp_Sample_Project/Deploy_Server/rest-tomcat/logs/catalina.out
• Webapp_Sample_Project/Deploy_Server/management-tomcat/logs/catalina.out

We hope you enjoy the new sample, and please let us know if you have any questions!

[joshorva]

The sample REST Web App has a create function that would be easier to use (especially from JavaScript) if the "create" method in ContextService.java returned "Response.ok ().entity (contextBean).build ();" instead of the "created()" response.

[tweissin]

Hi Joseph,

Thanks for the feedback.  Can you provide a specific example where it makes it easier in Javascript?  The typical response on an HTTP POST where an object is created is 201 (created).  OK would be a 200.  See the HTTP spec on this: RFC 2616 - Hypertext Transfer Protocol -- HTTP/1.1

Tom

[joshorva]

Actually, your code is well written and seems to comply with the spec. I was just noticing that in your code, after you create the object, you just return a URL to the object in the Location Header. This is the correct logic per the spec.

However, you do have the entire object in your hands at the time the method returns. The "ok" method on the Response class could return the entire object rather than just the URL. If I wanted to see the object I just created, then I have to go back to the server and ask for it.

Also, at the client side, the HTTP response is empty when using the "created" method on the Response class at the server side. In JavaScript (as a client), I need to notice that the response is empty, then go look at the Location Header for a URL. This causes the JavaScript developer to have to write a special case in the logic to handle responses from your server.

Overall, given that your code is well written and complies with the spec. I cannot recommend or ask for any code change. Maybe this post is just a rant on the spec.

[sajith]

Thanks Joseph, appreciate your feedback.

Would you like to share with the community, at a high level, what you are trying to accomplish with the REST sample code?

Sajith Kaimal

Product Manager, Context Service