KaTe RESTful adapter for SAP Process Integration: Introduction

RESTful Adapter for SAP Process Integration
Introduction & Overview

RESTful Adapter - Basics

What can the RESTful adapter do for you?


What can the RESTful adapter do for you?
Enable you to use SAP Process Integration to:
 Publish „Pragmatic“* REST Services in XML & JSON
 Invoke any„possible“ REST API or HTTP Resource

*) for a reference visit the excellent APIGee blog series on the topic


It‘s more then an just another adapter!


It‘s more then an just another adapter!
 Convention over Configuration driven approach!
 (using metadata means less configuration)

 API Console & WADL support to test & communicate with
stakeholders

It‘s Developer & Operations „friendly“


The 3 main building blocks of the adapter:
 The adapter runtime

Adapter

 PI sender/receiver channels
Describes

 Design Conventions
 Model HTTP communication by convention
 Metadata enables API Console

 Web UI (on top of adapter)
 Test HTTP Calls
 Display API Console & WADL*

Design Conventions
(WSDL/Msgs/JSON)

Enables
Web UI

*) available upwards PI >= 7.30


What do we mean by Design Conventions?


What do we mean by Design Conventions?
 ESR Conventions to model http calls as PI messages
 ESR Conventions to group resources as service interfaces
 Conventions to use XML internal and „speak“ JSON externally


What is the benefit of this Design Conventions?
 ESR metadata drives the API Console / WADL
 Explain your REST API in a simple Web UI!

 PI tools (mappings) can access any attribute of a http call
 No dynamic configurations or adaper modules needed!

 Test drive any http call from the adapter Web UI
 Testdrive http calls before building a complete scenario

 Convention over Configuration aproach!


.. JSON is enabled by Conventions too!


.. JSON is enabled by Conventions too!
 Any published RESTful service is usable with XML & JSON
 The adapter uses http content negotiation features to detect
the expected content (Accept & Content-type headers)
 No intensive configuration for JSON needed (modules etc...)
 Only choose: „XML compliant“ or „JSON compliant“ how XML turns
into JSON and back...

RESTful Adapter – Design Coventions

Action speaks louder then words
Let‘s see how it works by an example that comes with the
adapter!


Action speaks louder then words
 The adapter comes with a full CRUD example of a Partner
resource stored in a database (along with more examples)
 We will take a look at the example how a http POST call is
modeled and published by the conventions!


Our example:
 http POST call request with partner data
 that will return 201 Created status a location link to the new
partner resource
Adapter
POST http://myhost:50000/../Partner
HTTP
Client

Location: http://myhost:50000/../Partner/1


Our example request as http call:
POST /ROAWeb/Resources/Partner?sample=123 HTTP/1.1
Host:
myPIHost:50000
Accept:
application/xml
Content-Type:
application/xml; charset=utf-8
Authorization:
Basic aHR0cHdhdGNoOmY=
SampleHeader: testValue
<?xml version="1.0" encoding="UTF-8"?>
<Partner>
<firstName>Anton</firstName>
<lastName>Schmitt</lastName>
<birthday>1977-01-12</birthday>
<email>a.schmit@kate-group.com</email>
</Partner>

URI Path, Method,
Query Parameters

Http headers
(we‘re interested in
sample header)

POST data (body)


Our example request as PI request message
<urn:POST_Request xmlns:urn="urn:my:resource">
<identification>
<resource name="Partner"/>
<query><sample>123</sample> </query>
</identification>
<headers>
<SampleHeader>testValue</SampleHeader>
</headers>
<body>
<Partner>
<firstName>Anton</firstName>
<lastName>Schmitt</lastName>
<birthday>1977-01-12</birthday>
<email>a.schmit@kate-group.com</email>
</Partner>
</body>
</urn:POST>

Parsed URI Path, Method,
Query Parameters

Http headers
(we‘re interested in
sample header)

POST data (body)


And how would the response look like?


Our example response as PI response message:
<urn:POST_Response xmlns:urn="urn:my:resource">
<httpStatusCode>201</httpStatusCode>
<headers>
<location>
http://myHost:50000/ROAWeb/Resources/Partner/1
</location>
</headers>
</urn:POST>

HTTP Status: 201 Created
Http headers
(e.g.: here Location!)

*) You might wonder about the origin of the Location header,
this will be a few slides on ;)


Our example response as http call:
HTTP/1.1 201 Created

HTTP Status: 201 Created

….
Content-Type: application/xml; charset=utf-8
Location: http://myhost:50000/ROAWeb/Resources/Partner/1

Http headers
(e.g.: Location!)


Now wasn‘t that simple? 


Now wasn‘t that simple? 
By that convention you set/access in a mapping:
 any path or resource id information (pre parsed)
 any query parameter
 any header parameter
 any http status code (or reason)
 any body (payload) – raw or as XML*


You might now just go and try the call with the API Console
 As any call modeled by with this convention is exporable
through the API Console
Just go here* on your PI Install:
http://<yourPIHost>:50000/ROAWeb/Administration

*(/ROAWeb is the base path of the adaper)


The API Console enables you to:
 Invoke RESTful Services (with XML & JSON)
 Displays query/header parameters or the schema
 Generates sample calls for PUT/POST requests


The API Console (for our POST Request)

Send
Payload
Generate Sample Request
Display Schema
XML / JSON
Display result


Wait....but how did we create a current location header?


Wait....but how did we create a current location header?
 The adapter comes with a mapping lib to construct relative &
absolute links in the context of a call easily*
 The functions take your resource ID and returns the current
URI path + ID similar like Java REST frameworks (e.g. Jersey)
 (e.g. Supply „1“ turns into http://myhost:50000/.../Partner/1 )

*)Note! This feature is restricted to certain SP Levels (see SAP Note ) .
However we have a workaround for older versions ;)))


And dynamic resource uri‘s by calling a RESTful servcie?


And dynamic resource uri‘s by calling a RESTful servcie?
 As in previous example stated anything can be set
 Dynamic (in a Message Mapping)
 Static (in a Channel Configuration)
 Or both combined

 URLs, URIs, Resource Ids, Host, Port, etc...

RESTful Adapter - Resources

How are different calls to a resource grouped in an PI interface?


3 different ways to do it, group by:
 1 Interface per resource (e.g. Simple CRUD) that responds to
all HTTP Methods on this resource („Method oriented“)
 1 Interface hosts several resources and responds to all HTTP
Methods below one base path („API oriented“)
 Generic: Just receive anything below one base path
(„Generic“)


E.g. Our example Partner resource with CRUD methods

/<baseURI>/Partner
Bound by
channel

Service Interface: Partner
Operations:
POST (Request/Response)
GET (Request/Response)
PUT (Request/Response)
DELETE (Request/Response/Fault*)

*) Faults are not mandatory but usable if needed to cover fault replies
from receiver adapters

RESTful Adapter – Errors & HTTP Status

And how about PI faults & system errors?

RESTful Adapter – Erros & HTTP Status

Few facts first:
 RESTful HTTP Status treatment and PI internal
Success/Errorhandling differs!
 PI: Response(happy Path), (defined) Faults & System Erros on
Transport
 RESTful: Plain HTTP Status Code

RESTful Adapter – Erros & HTTP Status

The adapter closes this gap by:
 Enable you to return any http status in published Services
from regular response or fault messages (System Errors
default to 500, but could be overriden)
 Enable you to receive any http status for inspection / usage
as regular response message from a receiver channel (or by
your choice as fault or system error)

RESTful Adapter - JSON

And how about JSON ?

RESTful Adapter - JSON

And how about JSON ?
 Any JSON input or output is available as XML internally in PI
 The next few examples show the 2 different ways to do it to:
 Work XML „centric“ or
 Work JSON „centric“


.. JSON „XML centric“ example!
{

JSON

"tns:company": {
"@xmlns:tns": “urn:my:comp",
"name": "My Company",
"address": {
"city": "München",
"zipCode": "83503",
"houseNumber": "93a",
"country": “DE"
}
}
}

XML
<tns:company xmlns:tns=“urn:my:comp">
<name>My Company</name>
<address>
<city>München</city>
<zipCode>83503</zipCode>
<houseNumber>93a</houseNumber>
<country>DE</country>
</address>
</tns:company>

This is forth & backward compatible!


.. JSON „JSON centric“ example!

JSON
[
"1",
"2„,
3
]

XML
<a class="array">
<e type="string">1</e>
<e type="string">2</e>
<e type="number">3</e>
</a>

This is forth & backward compatible!

RESTful Adapter - Operations

And how about operations & monitoring?

RESTful Adapter - Operations

And how about operations & monitoring?
 Channels can adjust log levels to show http information
 None, only headers or all (see below)

Method & URI

Headers

Payload

RESTAdapter - Security

What Security standards are supported?





Basic Authentication
NTLM 1.x/2.x
SSL Client Certificate
oAuth1 / 2

RESTAdapter - Misc

What about other misc HTTP topics?

RESTAdapter - Misc

What about other misc HTTP topics?
E.g.:
 Posting and receiving Form Posts – fully supported
 Fits often as more „natural“ choice

 Post File Uploads – fully supported as multipart request
 Imagine posting a form with documents to start a Process?

RESTful Adapter - Samples

And what Samples do we provide „out of the box“?


Samples for publishing RESTful Example Services:
 Publish REST Service in XML/JSON from relational Database
(GET/PUT/POST/DELETE, JSON, Location Headers)
 REST Form POST Request


Samples how to invoke RESTful Sample Services:
 Call Twilio SMS API (JSON, Form Post, AuthToken)
 Call LinkedIn API (oAuth1, JSON/XML)
 Call Salesforce API (oAuth2, JSON/XML, PATCH Method)

RESTful Adapter

Interested in our SAP Certified offer?

We are pleased to hear your feedback

30 Day trial of the adapter available!

RESTful Adapter

Interested in our SAP Certified offer?

Contact us at :





WWW: http:www//kate-group.com/
T +49 711 90 79 64 65
F +49 711 90 79 64 66
E info@kate-group.com

KaTe RESTful adapter for SAP Process Integration: Introduction

KaTe RESTful adapter for SAP Process Integration: Introduction

Recommended

More Related Content

What's hot

What's hot(19)

Viewers also liked

Viewers also liked(7)

Similar to KaTe RESTful adapter for SAP Process Integration: Introduction

Similar to KaTe RESTful adapter for SAP Process Integration: Introduction(20)

Recently uploaded

Recently uploaded(20)

KaTe RESTful adapter for SAP Process Integration: Introduction

Editor's Notes