(ATS4-DEV04) Protocols as RESTful Services and RESTful URL Routing

(ATS4-DEV04) Protocols as RESTful Services and RESTful URL Routing

Jon Hurley

Senior Manager, Platform R&D

Jon.Hurley@accelrys.com

The information on the roadmap and future software development efforts are intended to outline general product direction and should not be relied on in making a purchasing decision.

• Configuring Protocols as Service Endpoints

• REST

• Protocols as RESTful services

• Long Running Jobs

Summary

Pipeline Pilot Integration Points

DBs

Pipeline Pilot Enterprise Server

Protocol Runtime Environment

VB Script (On

Client)

Run Program

Java Perl Python VB Script

(On Server)

Admin Portal Help Portal Web Apps Web Services API

.NET SOAP &

HTTP Telnet /

FTP SSH / SCP

ODBC / JDBC

VB Script Cmd Line Java

Classes Perl

Scripts .NET

Classes

REST Service

SOAP Service

Cmd Line Server Integration Extend pipelines with new components that integrate your code, data and services.

Professional Client

Run Protocol Command Line

Client

Web Browser

Web Port

JavaScript Client SDK

JavaScript Client

.NET Client SDK

.NET Client

Java Client SDK

Java Client

SOAP Client

Client Integration Build clients that connect to Pipeline Pilot and run protocol services.

HTTP Client

Http

SOAP APIs

Web Services API & Client SDKs

XML Protocol Database

Java SDK

Allows cross-platform access to Pipeline Pilot services

Java Servlets, JSP Java Applications

.NET Applications

Web Applications

Perl SOAP::Lite & other SOAP libs

JavaScript SDK

.NET SDK Pipeline Pilot Server

Browsers, Http Clients

Client Server

Authentication Layer

• Mapping protocols to Web Services

– “Visual” Services

– Parameter Style

– Document Style

Protocols as Web Services

• Representational State Transfer

• Typically pass documents (eg XML, JSON) between client & server that represent state of a resource

• Uses existing verbs rather than creating arbitrary function names – GET, PUT, POST, DELETE

• Resources identified by URI, so URI mapping required to underlying functions

RESTful Services

8

RESTful URIS refer to resources

Two types of URIs Collection - http://example.com/compounds/

Element - http://example.com/compounds/acc123456

5 Common Methods

Method Purpose

GET For retrieving a data resource or a resource collection

POST For creating a new resource

PUT For replacing a resource

PATCH For updating resource content

DELETE For removing a resource

RESTful URIs

9

• Collection of animals

• Stored in a cache loaded from ‘data/Tables/zoo.txt’

• List, edit, delete animal records

• Set of protocols that are exposed as RESTful services

• Demonstrated using the Chrome Browser ‘Advanced Rest Client’

Zoo Examples

• Accessing a protocol service from REST browser plugin

Demo

11

http://{server}/zoology/animals/

[

{"id":1,"animalname":"aardvark"},

{"id":2,"animalname":"antelope"},

{"id":3,"animalname":"bass"},

{"id":4,"animalname":"bear"},

…

List Service

12

http://{server}/zoology/animals/1

[

{"id":"1","animalname":"aardvark","type

":"mammal","milk":"1","legs":"4","tail"

:"0","eggs":"0","feathers":"0"}

]

Individual Animal Service

13

http://{server}/zoology/banimals/

[

{"id":3,"animalname":"bass"},

{"id":4,"animalname":"bear"},

{"id":5,"animalname":"boar"},

{"id":6,"animalname":"buffalo"}

]

List the ‘B’ Animals

14

http://{server}/zoology/canimals/xml

<?xml version="1.0" encoding="UTF-8"?>

<animals>

<animal id="7" animalname="calf" />

<animal id="8" animalname="carp" />

<animal id="9" animalname="catfish" />

<animal id="10" animalname="cavy" />

</animals>

List the Animals with an XML format

15

• URL Route definitions are provided in package files

• In your package define the routes in a urls.conf file

• Include a reference to this file in package.conf:

…

# URL routing configuration

Include $(package)/urls.conf

Defining URL Routes

16

<url REST AUTH>

method GET

request /zoology/animals/

protocol Protocols/Web Services/AcclDev/zoo/Actions/animal/List

summary List all animals in the zoo.

<url>

request /zoology/banimals/

param NameFilter B

querystring Off

summary List all animals whose name starts with the letter B.

</url>

</url>

Defining URL Routes

17

List Protocol

Reviewing RESTful service protocols

18

• Add new animals • POST: {root}/zoology/animals/ • Header: Content-type: application/json • By default the body is stored in the first parameter on the

protocol (override with _bodyParam in URL route) • Edit an existing animal

• PUT: http://meteorbs:9944/zoology/animals/

• With full data record • PATCH: http://meteorbs:9944/zoology/animals/

• With partial data record

Some Edit URLs

19

• Services can use these methods to control the return format

• Accept Header

• Accept: application/json

• Format Query String argument

• http://{server}/zoology/formanimals/1

• OR

• http://{server}/zoology/formanimals/1?format=xml

• Overrides the format from the Accept header

Specifying the return format

20

If the action may take more than a few seconds to run then make it a long running job so it can be polled from the client.

In package.conf

…

<url>

method GET

request /myapp/slowjob

protocol Protocols/Examples/My Protocol

param _blocking 0

</url>

…

A Long Running Job

21

Running Job RESTful URLs

Method URL path Description

GET /jobs/ List of the current user’s jobs GET /jobs/job-id Details for the specified job GET /jobs/job-id/status Status code for the job (e.g. running) GET /jobs/job-id/files List of links to job directory files GET /jobs/job-id/results Results of the job DELETE /jobs/job-id Release the job (terminate if still running) DELETE /jobs/job-id/stop Stop the current job

22

• Use JSON Reader (or XML Reader) or HTTP Connector

• E.g. $(ServerRoot)/zoology/animals/

Accessing RESTful services from Protocols

• Package developers can configure RESTful endpoints for protocols

• Next Steps

– Get the demo package with which to experiment • testpkg-svc1

– aep_restful_web_services.pdf

Summary