  Oracle® Beehive RESTful Web Services API Reference
  Release 2 (2.0.1.7)
  E16658-04

Introduction to Oracle Beehive RESTful Web Services

Oracle Beehive RESTful Web Services are APIs that enables you to develop Web applications. These APIs are implemented with the principals of REST, Representational State Transfer.

This document introduces you to REST and describes the structure of the Oracle Beehive RESTful Web Services API Reference. It covers the following topics:

Introduction to REST
Conventions for Describing Oracle Beehive RESTful Web Services Procedures

Introduction to REST

RESTful (Representational State Transfer) Web services are Web services that are implemented with the principles of REST:

API URLs point to the resource being used rather than a generic method endpoint.
Requests use standard HTTP verbs for simplified CRUD methods: Create, POST; Update, POST; Retrieve, GET; and Delete, DELETE.
Create and Update data is sent as a POST body (JSON and XML).
Every request returns a full (or at least standard) representation of the object created, updated, or retrieved.

For example, suppose you want to create a RESTful Web service to manage a collection of books. In REST, a book would be represented by a resource, which is uniquely identified by a URI. For example, REST could represent the collection of books with the URI http://www.example.com/books. If you are using the ISBN to identify books in the collection, the URI http://www.example/books/12345 could represent a book with the ISBN 12345.

To define an action that can be performed on this collection, such as adding a book, you associate the action with an HTTP method. In this case, you could associate the action of adding a book with the HTTP POST method.

In general, RESTful Web services associate the basic CRUD (Create, Read, Update, and Delete) operations as follows.

HTTP Method	CRUD Equivalent	Comment
POST	Create	The payload is a representation of new object (for example, an XML document to represent a book).
GET	Read	REST APIs usually accept one or more IDs in the URI to indicate which items to retrieve.
PUT	Update	As with POST, the payload is a representation of the object being updated
DELETE	Delete	As with GET, REST APIs by convention accept one of more IDs as either a query parameter or embedded in the URI.

The term representation is the structured payload corresponding to programming objects. Oracle Beehive RESTful Web Services use Java Script Object Notation (JSON) or XML to represent objects.

There is an emerging standard to define RESTful Web services called Web Application Description Language (WADL). WADL is the REST counterpart to W3C Web Services's WSDL.

Conventions for Describing Oracle Beehive RESTful Web Services Procedures

Some procedures described in this API reference use the following abbreviated convention to describe method calls:

{Step number} Return(Object that is returned) HTTP-METHOD /resource/foo Send(Object to Send) Params(params)

For example, the following steps demonstrate how to create a team workspace:

(List) POST /enpr/list (predicateAndSortListParameters) ()
(List) POST /ttws/list (predicateAndSortListParameters) (parent=enterpriseID from 1)
(teamWorkspace) POST /wstm (teamworkspaceCreator use ttws from 2) ()

This sequence of method calls is equivalent to the following:

This method returns an object of type list. Call the POST method /enpr/list to retrieve a list of all enterprises in the system. This method requires a payload of type predicateAndSortListParmeters. Do not specify any parameters.
This method returns an object of type list. Call the POST method /ttws/list to retrieve a list of team workspace template objects. This method requires a payload of type predicateAndSortListParameters. Specify in the parent parameter the enterprise ID obtained in step 1.
This method returns an object of type teamWorkspace. Call the POST method /wstm to create a team workspace. This method requires a payload of type teamworkspaceCreator. In the teamworkspaceCreator, specify the teamWorkspaceTemplate retrieved in step 2. Do not specify any parameters.

Top