Oracle® Beehive RESTful Web Services API Reference Release 2 (2.0.1.7) E16658-04 |
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:
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.
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:
This sequence of method calls is equivalent to the following:
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. 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. 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 |