Intelligent Operations Center 1.6.

0
Introduction to the Service APIs

Copyright IBM Corp. 2013.

Course materials may not be reproduced in whole or in part without prior written permission of IBM.

Introduction
Need simple, standard way to access REST service data from serverside code
Impractical to force server-side code to make HTTP REST call
REST service data may be stored outside of a database
Support JSON results while allowing for future formats such as XML
Follow current REST coding standards
Standardized exceptions
Avoid calling low-level JDBC code since these implementations vary
greatly

Copyright International Business Machines Corporation 2013. All Rights Reserved.

US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with
IBM Corp.
Copyright IBM Corp. 2013.

Supported HTTP Verbs

HTTP Verb

CRUD Operation Type

Description

GET

Read

Safe

Return the current state of a

resource

POST

Create

Unsafe

Creates a new resource

PUT

Update

Idempotent Updates the resource state

DELETE
Safe

Delete

Idempotent Removes the resource

Operation must be read-only.

Result can be cached.

Unsafe
Operation is read-write.

Idempotent
Operation can be repeated without affecting the state of the resource.
Latin for having the same power.

Copyright IBM Corp. 2013.

IOC REST Standards URI Format

All REST URIs use the format

/ibm/{domain}/api/{name}-service/{resource}/{id}
domain: ioc for IOC product
name: component name all lower case
resource: plural form of the resource
id: (optional) resource ID to act on
Examples
/ibm/ioc/api/sysprop-service/sysprops
/ibm/ioc/api/sysprop-service/sysprops/1
/ibm/ioc/api/filter-service/panels
/ibm/ioc/api/datasource-service/datasources
Copyright IBM Corp. 2013.

IOC REST Standards HTTP Status Codes

Status Code

Description

200 (OK)

Returned by a successful GET, PUT, or POST.

204 (No content)

Returned by a successful DELETE.

400 (Bad request)

Returned when supplied data are not valid or missing

(e.g. any input validation error).

401 (Unauthorized)

Returned when the user is not authenticated to the

server and the request requires authentication.

403 (Forbidden)

Returned when the user is authenticated to the server

but not authorized to complete the request.

404 (Not found)

Returned by a GET or PUT when a resource does not

exist. If returning a list, return a 200 and an empty list.

409 (Conflict)

Returned by a PUT when the last modified timestamp

supplied by the caller does not match the current value.

500 (Internal server error) Returned when an unexpected error occurs.

Copyright IBM Corp. 2013.

General Guidelines
Response
A successful POST/PUT request response should include the
new/modified JSON object
Optimistic Concurrency (PUT)
Server compares the resource's current last update timestamp
with the value supplied in the request.
Request processed only if the timestamps match.
Return an HTTP status code of 409 (Conflict) if the timestamps
do not match.
Search (GET)
Searches should be performed by submitting a GET request
along with a query string.
Do not use path parameters for searching. For a complex
search or filter criteria, use query parameters.
Copyright IBM Corp. 2013.
6

General Guidelines
URI Paths
Path parameters should only be used for identifying resources.
Do not use path parameters to add new verbs to the API.
For example, do not use .../{id}/start
Common Properties
id: integer
Uniquely identifies each resource
lastUpdateDate: long
Timestamp value used for concurrency check
Translated Properties
Resource includes the untranslated propert with the translated
property prefixed with i18n
For example: label and i18nLabel
Copyright IBM Corp. 2013.

Design

Web browser
JSON

REST service

Server-side code

POJO
POJO

Data service
POJO

JDBC
Copyright IBM Corp. 2013.

Implementation com.ibm.ioc.rest
REST service
RestResource
Abstract class containing common REST resource methods
All concrete REST resource classes extend this class
RestUtils
Common REST utilities
Exceptions correspond to HTTP response status codes
BadRequestException

400

ConflictException

409

ForbiddenException

403

InternalServerErrorException

500

NotFoundException

404

Copyright IBM Corp. 2013.

Implementation com.ibm.ioc.rest
Data service
IDataService
Interface defining the minimum required methods (create, get,
update, delete) and the possible exceptions
DataServiceImpl
Abstract class implementing the IDataService interface
All interface methods implemented as throwing an exception
All concrete data service implementations extend this class and
override the necessary methods

Copyright IBM Corp. 2013.

10

Implementation com.ibm.ioc.rest
POJO
IData
Marker interface for all POJOs returned from the data service
DataImpl
Abstract class implementing IData interface
Defines common REST attributes (id, lastUpdateDate, and
messages)
All concrete POJO implementations extend this class

Copyright IBM Corp. 2013.

11

JDBC Layer Exceptions com.ibm.ioc.jdbc.utils

JDBC
JdbcGeneratedKeysException
Unable to retrieve generated keys
JdbcInsertException
Unable to insert a row into the database
JdbcParameterException
JDBC parameter value is not valid
JdbcUpdateException
Unable to update a row in the database

Copyright IBM Corp. 2013.

12

Sending Messages from the Layers com.ibm.ioc.rest

RestMessage
Defines the data required to display a translated message
messageId: the message ID
messageText: the untranslated message text
i18nMessageText: the translated message text
List<RestMessage> included in DataImpl
Returned with the result of the REST service
ExceptionMessages
Contains List<RestMessage>
Included in any ISSException

Copyright IBM Corp. 2013.

13

Displaying Messages
Library functions com.ibm.ioc.Library JavaScript class
publishMessage(messageId, i18nMessageText)
publishRestMessages(result, defaultMessageId,
defaultI18nMessageText)
result: zero or more success messages returned from REST
service
publishRestErrorMessages(error, defaultMessageId,
defaultI18nMessageText)
error: zero or more error messages returned from REST
service
Added features
Determines the correct message type (error, warning, info)
based upon last character of message ID
Automatically adds the current time in the browser's preferred
format
Copyright IBM Corp. 2013.
14

Displaying Messages
IOC Portal themes
Displays messages as an IDX SingleMessage in a scrolling div

Copyright IBM Corp. 2013.

15

Example Implementation Sysprop

com.ibm.ioc.sysprop.rs.SyspropResource
Sysprop REST service
Extends RestResource
com.ibm.ioc.sysprop.Sysprop
Sysprop POJO
Extends DataImpl
com.ibm.ioc.sysprop.SyspropDataService
Sysprop REST server-side data service
Extends DataServiceImpl
com.ibm.ioc.sysprop.SyspropJdbcUtils
Sysprop JDBC utilities
Extends JdbcUtils
Copyright IBM Corp. 2013.

16

Example Implementation Sysprop

To send a message in an IData result from the JDBC class

// add the success message
sysprop.addMessage(RestUtils.createRestMessage("CIYRS0000I", "SyspropApp",
locale, "CIYRS0000I", new Object[]{sysprop.name}));

To send a message in an ISSException

} catch (DuplicateKeyException e) {
JdbcInsertException exc = new JdbcInsertException(e);
RestMessage rm = RestUtils.createRestMessage(
"CIYRS0071E", "SyspropApp", locale, "CIYRS0071E",
new Object[]{sysprop.name});
exc.addMessage(rm);
throw exc;
}

Copyright IBM Corp. 2013.

17

Example Implementation Sysprop

To display REST success and error messages in dojo UI code

when(this.store.add(item),
lang.hitch(this, function(result) {
this._library.publishRestMessages(
result,
"CIYRS0000I",
this._library.i18nFormat(this.i18nRes.CIYRS0000I,
item.name));
}),
Default message
lang.hitch(this, function(error) {
this._library.publishRestErrorMessages(
error,
"CIYRS0000E",
this._library.i18nFormat(this.i18nRes.CIYRS0000E,
item.name));
})
);

Copyright IBM Corp. 2013.

18

data

Questions?

Copyright IBM Corp. 2013.

19