OData Complete Reference

OData in a Nutshell August 2011

INTE

RNA

L

Objectives

At the end of this module, you will be able to: Ÿ  Understand the OData Standard and how it works. Ÿ  Understand how OData uses the Atom Protocol. Ÿ  Understand how to pass input parameters to OData Services.

©  2011 SAP AG. All rights reserved.

RKT

2

Gateway Core Technology

What is the Open Data Protocol?

OData with SAP Annotations

REST

Metadata Repository

Service Adaptation

Service Adaptation

Supportability Monitoring Security

Based on industry standards

-  HTTP, XML, Atom REST-based architecture

OData for SAP OData

-  Based on the HTTP protocol Atom is a combination of two standards

Atom

-  Atom Syndication Protocol and Atom

XML

Publishing Protocol

-  XML Based

HTTP

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.

RKT

3

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:

HTTP Verb

CRUD Method

POST

Create

GET

Read

PUT

Update

DELETE

Delete

Ÿ  URL is used to define the resource that is being acted upon. –  Example: http://servername:http_port/sap/customer/12345 Customer entity ©  2011 SAP AG. All rights reserved.

Customer ID 12345 RKT

4

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 based 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.

RKT

5

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.

RKT

6

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.

RKT

7

Atom in OData Details

©  2011 SAP AG. All rights reserved.

RKT

8

Atom in OData Details Continued…

Atom Feed Defined

Atom Content – the business object data

©  2011 SAP AG. All rights reserved.

RKT

9

Atom in OData Details Continued…

Atom Feed Defined

Atom links – where to get more information about the entity

©  2011 SAP AG. All rights reserved.

RKT

10

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.

RKT

11

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/BankCollection

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 results Ÿ  $skip – used to skip ahead X number of entities in the returned list, example: $skip=5, skips the first 5 results in the list. –  Often combined with $top to page thru a list, example: $top=5&$skip=5 – returns the second 5 results in the list.

Ÿ  Many others defined by OData. Note: not all supported by Gateway. ©  2011 SAP AG. All rights reserved.

RKT

12

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 HREF link to the RetrieveEntity operation for that entity:

©  2011 SAP AG. All rights reserved.

RKT

13

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.

RKT

14

OData Operations – InsertEntity Continued

The InsertEntity operation creates an entity. Successful execution of the operation returns HTTP 201 status code along with the location of the newly created entity will be returned. Successful Response Header:

Successful Response Body:

©  2011 SAP AG. All rights reserved.

RKT

15

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.

RKT

16

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.

RKT

17

Summary

You should now be able to Ÿ  Understand the OData Standard and how it works. Ÿ  Understand how OData uses the Atom Protocol. Ÿ  Understand how to pass input parameters to OData Services.

©  2011 SAP AG. All rights reserved.

RKT

18

© 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 be changed without prior notice. Some software products marketed by SAP AG and its distributors contain proprietary 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, System x, System z, System z10, System z9, z10, z9, iSeries, pSeries, xSeries, zSeries, eServer, 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, Intelligent Miner, WebSphere, Netfinity, Tivoli and Informix are trademarks or registered trademarks of IBM Corporation. Linux is the registered trademark of Linus Torvalds in the U.S. and other countries. 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 countries. 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 license for technology invented and implemented by Netscape. SAP, R/3, SAP NetWeaver, Duet, PartnerEdge, ByDesign, SAP BusinessObjects Explorer, StreamWork, and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP AG in Germany and other countries.

©  2011 SAP AG. All rights reserved.

Business Objects and the Business Objects logo, BusinessObjects, Crystal Reports, Crystal Decisions, Web Intelligence, Xcelsius, and other Business Objects products and services 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 Sybase products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of Sybase, Inc. Sybase is an SAP company. All other product and service names mentioned are the trademarks of their respective companies. Data contained in this document serves informational purposes only. National 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 express 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, developments, 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 notice. 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 of 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 materials. This limitation shall not apply in cases of intent or gross negligence. The statutory liability for personal injury and defective products is not affected. SAP has no control over the information that you may access through the use of hot links contained in these materials and does not endorse your use of third-party Web pages nor provide any warranty whatsoever relating to third-party Web pages.

RKT

19