1st October

In OData Nutshell
2011 August
OData in a Nutshell
August 2011

Objectives

At the end
..
Understand
..
Understand
..
Understand

of this module, you will be able to:

the OData Standard and how it works.
how OData uses the Atom Protocol.
how to pass input parameters to OData Services.

2011 SAP AG. All rights reserved. 2RKT

What is the Open Data Protocol?

Gateway CoreTechnology OData with SAP Annotations
REST
Service
Adaptation
Metadata
Repository
Service
Adaptation
Supportability
Monitoring
Security
Based on industry standards
OData for SAP
REST-based architecture
HTTP, XML, Atom OData
-Based on the HTTP protocol
Atom
Atom is a combination of two
standards
XML
-Atom Syndication Protocol and Atom
Publishing Protocol
HTTP
-XML Based
OData
http://www.odata.org
-Defines Data Types, Service
Metadata, Service Runtime ODBC for the Web
-Allows for Entity Relationships and
Dynamic Navigation
2011 SAP AG. All rights reserved. 3RKT

REST

Representational State Transfer

REST is a set of architectural principals that can be used to define Web

Services.
First introduced by Roy Fielding in his doctorial dissertation in the year 2000.
HTTP protocol is an example of a system that implements the principles of REST.
..
Uses HTTP verbs to communicate what action to take. Verbs map to CRUD methods:
2011 SAP AG. All rights reserved. 4RKT
..URL is used to define the resource that is being acted upon.
Example: http://servername:http_port/sap/customer/12345
HTTP Verb CRUD Method
POST Create
GET Read
PUT Update
DELETE Delete
Customer entity Customer ID 12345

Atom

Atom is the combination of two standards: Atom Syndication Format and

Atom Publishing Protocol
Atom standards were originally created for publishing and subscribing to web bas
ed
content (news reports, blogs, etc.).
Atom Syndication Format
..
Defines the format for document feeds.
..
In OData, the documents are the data being acted upon (Business Objects, etc).
Atom Publishing Protocol
..
Defines how to read and maintain documents.
..
Atom uses GET, POST, PUT, DELETE HTTP verbs as described the REST architecture.
2011 SAP AG. All rights reserved. 5RKT

ODBC for the Web

OData can be used to access table like structures much the same way ODBC
does.
Entity Data Model (EDM) used to describe OData Services.
EDM modeling tools available to model OData Services:
Each entity can support Create,
Read, Update, and Delete (CRUD)
operations
Can navigate relationships
Complex Types supported
2011 SAP AG. All rights reserved. 6RKT

OData Metadata
OData defines a Metadata format based on the Entity Data Model in XML
(edmx).
To access a service s metadata document use the $metadata command:
The returned document is the service s edmx metadata + SAP Metadata (S-Data):

2011 SAP AG. All rights reserved. 7RKT

Atom in OData Details

2011 SAP AG. All rights reserved. 8RKT

Atom in OData Details Continued

Atom Feed
Defined
Atom Content
the business
object data
2011 SAP AG. All rights reserved. 9RKT

Atom in OData Details Continued

Atom Feed
Defined
Atom links where to get
more information about the
entity
2011 SAP AG. All rights reserved. 10RKT

OData for SAP

Extra Metadata

OData for SAP is extra metadata that can be found in the service s metadata
document
To access a service s metadata document use the $metadata alias:
The returned document is the service s edmx metadata + SAP Metadata (S-Data):
OData for SAP contains: labels, annotations, etc.
Extra metadata that can be accessed via SAP proxy generators.
2011 SAP AG. All rights reserved. 11RKT

OData Operations

RetrieveEntitySet (QUERY)

OData defines a RetrieveEntitySet request to search for entities in an entity

set. It returns a list of matching entities.
Use HTTP GET verb to retrieve a feed of entities from an entity set.
The URL only contains the name of the entity set and any needed query string
parameters:
http://usphlrig15.phl.sap.corp:8001/sap/iw/rest/odata/sap/BANKGEBOODATA/BankColl
ection
Query string parameters defined by OData:
..
$filter
user for passing input parameters, example: $filter=airlineid EQ US
Other operators supported, GT, LT, AND, OR, etc. Learn more on OData website.
..
$top
used for getting the top X results, example: $top=5
returns the first 5 res
ults
..
$skip
used to skip ahead X number of entities in the returned list, example: $sk
ip=5, skips
the first 5 results in the list.
Often combined with $top to page thru a list, example: $top=5&$skip=5
e second 5 results
in the list.
..
Many others defined by OData. Note: not all supported by Gateway.
2011 SAP AG. All rights reserved. 12RKT

returns th

OData Operations

RetrieveEntity (READ)

The RetrieveEntity operation returns the details of a specific entity.

Use HTTP GET verb to execute the RetrieveEntity operation.
The URL of the RetrieveEntity operation is just the RetrieveEntitySet operation
URL
with the addition of the key properties
Note: Each Entity returned by the RetrieveEntitySet operation will contain an HR
EF
link to the RetrieveEntity operation for that entity:
2011 SAP AG. All rights reserved. 13RKT

OData Operations

InsertEntity (CREATE)

The InsertEntity operation creates an entity.

Use HTTP POST verb to execute the InsertEntity operation.
The URL used to execute the InsertEntity operation is the exact same used for
executing the RetrieveEntitySet operation.
The Request Header most include the attribute x-requested-with:
The Body of the request must contain the Atom Entry that represents the business
entity to be created:
2011 SAP AG. All rights reserved. 14RKT

OData Operations

InsertEntity Continued

The InsertEntity operation creates an entity.

Successful execution of the operation returns HTTP 201 status code along with th
e
location of the newly created entity will be returned.
Successful Response Header:
Successful Response Body:

2011 SAP AG. All rights reserved. 15RKT

OData Operations

UpdateEntity (UPDATE)

The UpdateEntity operation updates an entity.

Use HTTP PUT verb to execute the UpdateEntity operation.
The URL used to execute the UpdateEntity operation is the exact same used for
executing the RetrieveEntity operation.
The Request Header most include the attribute x-requested-with:

The Body of the request must contain the Atom Entry that represents the business
entity to be updated:
2011 SAP AG. All rights reserved. 16RKT

OData Operations

UpdateEntity Continued

The UpdateEntity request changes an entity.

If the update is successful, the server responds with:
Successful Response Header
204 HTTP Response Code:
As the response code text above signifies, no data is returned in the Response
Body:
2011 SAP AG. All rights reserved. 17RKT

Summary

You should
..
Understand
..
Understand
..
Understand

now be able to
the OData Standard and how it works.
how OData uses the Atom Protocol.
how to pass input parameters to OData Services.

2011 SAP AG. All rights reserved. 18RKT

 2011 SAP AG. All rights reserved

No part of this publication may be reproduced or transmitted in any form or for
any purpose
without the express permission of SAP AG. The information contained herein may b
e
changed without prior notice.
Some software products marketed by SAP AG and its distributors contain proprieta
ry
software components of other software vendors.
Microsoft, Windows, Excel, Outlook, and PowerPoint are registered trademarks of
Microsoft
Corporation.
IBM, DB2, DB2 Universal Database, System i, System i5, System p, System p5, Syst
em x,
System z, System z10, System z9, z10, z9, iSeries, pSeries, xSeries, zSeries, eS
erver, z/
VM, z/OS, i5/OS, S/390, OS/390, OS/400, AS/400, S/390 Parallel Enterprise Server
,
PowerVM, Power Architecture, POWER6+, POWER6, POWER5+, POWER5, POWER,
OpenPower, PowerPC, BatchPipes, BladeCenter, System Storage, GPFS, HACMP,
RETAIN, DB2 Connect, RACF, Redbooks, OS/2, Parallel Sysplex, MVS/ESA, AIX, Intel
ligent
Miner, WebSphere, Netfinity, Tivoli and Informix are trademarks or registered tr
ademarks of
IBM Corporation.
Linux is the registered trademark of Linus Torvalds in the U.S. and other countr
ies.
Adobe, the Adobe logo, Acrobat, PostScript, and Reader are either trademarks or
registered
trademarks of Adobe Systems Incorporated in the United States and/or other count
ries.
Oracle is a registered trademark of Oracle Corporation.
UNIX, X/Open, OSF/1, and Motif are registered trademarks of the Open Group.
Citrix, ICA, Program Neighborhood, MetaFrame, WinFrame, VideoFrame, and MultiWin
are
trademarks or registered trademarks of Citrix Systems, Inc.
HTML, XML, XHTML and W3C are trademarks or registered trademarks of W3C, World
Wide Web Consortium, Massachusetts Institute of Technology.
Java is a registered trademark of Sun Microsystems, Inc.
JavaScript is a registered trademark of Sun Microsystems, Inc., used under licen
se for
technology invented and implemented by Netscape.
SAP, R/3, SAP NetWeaver, Duet, PartnerEdge, ByDesign, SAP BusinessObjects Explor
er,
StreamWork, and other SAP products and services mentioned herein as well as thei

r
respective logos are trademarks or registered trademarks of SAP AG in Germany an
d other
countries.
Business Objects and the Business Objects logo, BusinessObjects, Crystal Reports
, Crystal
Decisions, Web Intelligence, Xcelsius, and other Business Objects products and s
ervices
mentioned herein as well as their respective logos are trademarks or registered
trademarks
of Business Objects Software Ltd. Business Objects is an SAP company.
Sybase and Adaptive Server, iAnywhere, Sybase 365, SQL Anywhere, and other Sybas
e
products and services mentioned herein as well as their respective logos are tra
demarks or
registered trademarks of Sybase, Inc. Sybase is an SAP company.
All other product and service names mentioned are the trademarks of their respec
tive
companies. Data contained in this document serves informational purposes only. N
ational
product specifications may vary.
The information in this document is proprietary to SAP. No part of this document
may be
reproduced, copied, or transmitted in any form or for any purpose without the ex
press prior
written permission of SAP AG.
This document is a preliminary version and not subject to your license agreement
or any
other agreement with SAP. This document contains only intended strategies, devel
opments,
and functionalities of the SAP product and is not intended to be binding upon SAP
to any
particular course of business, product strategy, and/or development. Please note
that this
document is subject to change and may be changed by SAP at any time without noti
ce.
SAP assumes no responsibility for errors or omissions in this document. SAP does
not
warrant the accuracy or completeness of the information, text, graphics, links,
or other items
contained within this material. This document is provided without a warranty of
any kind,
either express or implied, including but not limited to the implied warranties o
f
merchantability, fitness for a particular purpose, or non-infringement.
SAP shall have no liability for damages of any kind including without limitation
direct, special,
indirect, or consequential damages that may result from the use of these materia
ls. This
limitation shall not apply in cases of intent or gross negligence.
The statutory liability for personal injury and defective products is not affect
ed. SAP has no

control over the information that you may access through the use of hot links co
ntained in
these materials and does not endorse your use of third-party Web pages nor provi
de any
warranty whatsoever relating to third-party Web pages.
2011 SAP AG. All rights reserved. 19RKT