Appendix REST API Support

Overview

The REST API provides a standardized method for Next-Gen firewalls and third-party systems to interact with IPS. Representational state transfer (REST) or RESTful Web services are one way of providing interoperability between computer systems on the Internet. REST-compliant Web services allow requesting systems to access and manipulate textual representations of Web resources using a uniform and predefined set of stateless operations. In a RESTful Web service, requests made to a resource's URI will elicit a response that may be in XML, HTML, JSON or some other defined format. IPS supports JSON format only.

REST methods determine the HTTP method for manipulating the resources defined in the service operation. The kind of operations available include those predefined by the HTTP verbs GET, POST, PUT, DELETE and so on. The response may confirm that some alteration has been made to the stored resource, and it may provide hypertext links to other related resources or collections of resources. By making use of a stateless protocol and standard operations, REST systems aim for fast performance, reliability, and the ability to grow, by re-using components that can be managed and updated without affecting the system as a whole, even while it is running.

REST API Support for IPS involves only Configuration APIs. IPS supports only the GET, POST, PUT and DELETE APIs.

The valid and supported values are described in table.

HTTP Verb

Definition

DELETE

Delete an existing resource.

GET

Retrieve a representation of a resource.

POST

Create a new resource

PUT

Create a new resource to a new URL, or modify an existing resource to an existing URL.

The error codes supported are described in the table.

HTTP Verb

Definition

200 OK

Requesting for resource information successful using GET

Resource updation successful using PUT

201 Created

Resource creation successful using POST

204 No Content

Deletion of resource successful with no body. Even PUT, POST may return 204 if no errors or warnings seen

400 – Bad Request 

Any Request (GET/PUT/POST/DELETE, and so on) is invalid.

Example: Incorrect JSON format

401 – Unauthorized

Any REST Call with invalid credentials

403 – Forbidden

REST Call with valid credentials but no permission.

404 – Not found

Requested resource in URI does not exists

422 – Unprocessable Entity

Any validation/referential integrity errors that would result in failure of PUT/POST/DELETE request

500 Server Error

When IPS rest server is not responding

Authentication for REST APIs

Basic authentication using the HTTP authorization header is used to authenticate username/password on the Administrators authserver. It is expected that the user is already configured in the Administrators authserver. On a successful login, a random token (api_key) is generated and sent back as a JSON response. Further access to APIs can use this api_key in their Authorization header for access. The entire communication is over TLS. An example is explained below:

REQUEST

GET /api/v1/auth HTTP/1.1

Host: xx.xx.xx.xx

Authorization: Basic YWRtaW5kYjpkYW5hMTIz

Content-Type: application/json

RESPONSE

HTTP/1.1 200 OK

Cache-Control: no-store

Connection: Keep-Alive

Content-Type: application/json

Expires: -1

Keep-Alive: timeout=15

{ "api_key": "p5mMlc7RQu81R2NvssLCCZhP05kf0N2ONFeYeLXX6aU=" }

Authorization header for all future request should perform Basic Auth using above api_key value as username and password as empty.

REQUEST

GET /api/v1/configuration HTTP/1.1

Host: xx.xx.xx.xx

Authorization: Basic cDVtTWxjN1JRdTgxUjJOdnNzTENDWmhQMDVrZjBOMk9ORmVZZUxYWDZhVT06

RESPONSE

HTTP/1.1 200 OK

Content-Length ?283

Content-Type ?application/json

{ "

administrators":

{ "href": "/api/v1/configuration/administrators" }

, "

authentication":

{ "href": "/api/v1/configuration/authentication" }

, "

system":

{ "href": "/api/v1/configuration/system" }

, "

users":

{ "href": "/api/v1/configuration/users" }

}

Enabling REST API Configuration

The configuration of IPS can be accessed using REST APIs. The IPS configuration is represented in a JSON form when accessed using REST APIs. The structure of the JSON representation is very similar to the structure of IPS XML configuration.

A new admin UI option for users under "Administrators" authserver has been added. REST API authentication would be successful only for those users who have this option enabled.

To enable this checkbox:

  1. Go to Authentication > Auth. Servers >Administrators > Users > New/Update.
  2. Select the Allow access to REST APIs checkbox.
  3. Click Save Changes.