1 About the OPSS REST API

This section introduces the Oracle Fusion Middleware representational state transfer (REST) API for managing Oracle Platform Security Services (OPSS).

This chapter includes the following sections:

Introducing the OPSS REST API

The OPSS REST API provides access to core OPSS functionality over a REST interface. The REST API enables a wider range of languages and platforms to use OPSS services. The API also provides applications with the flexibility to use newer functionality without having to wait for the corresponding language-specific APIs to be implemented.

The services discussed in this reference include:

Registration Service – A service that is used to register a client with OPSS. A client must register with OPSS in order to use any of the other services. See Registering OPSS Clients.
Credentials Service – A service that is used to create and view credentials. See Managing Credentials in the Credential Store.
Keystore Service – A service that is used to manage keysores. See Managing Keystores.
Trust Service – A service that is used to create and validate trust tokens. See Creating and Validating Trust Tokens.
Authorization Service – A service that is used to authorize access to resources using a policy decision point system. See Authorizing Access.
Note:

To deploy OPSS REST API services, your domain must include the OPSS REST Service Application Template. You can select this template when creating your domain, or you can extend an existing domain to include it. For more information, see the following topics:
- Configuring Fusion Middleware Domains in WebLogic Domains Using the Configuration Wizard
- Oracle OPSS REST Service Application Template in Domain Template Reference

General URL Structure for OPSS Resources

Use the following URL to manage security:

https://host:port/opss/v2/resource

Where:

host:port—Host and port where Oracle Fusion Middleware is running.
resource—Relative path that defines the REST resource. Available resources are described throughout this guide. To access the Web Application Definition Language (WADL) document which defines each of the resources, specify application.wadl in the URL. For example:
```
https://host:port/opss/v2/application.wadl
```

Authenticating REST Resources

You access the Oracle Fusion Middleware REST resources over HTTP and must provide your Oracle WebLogic Server administrator user name and password.

For example, to authenticate using cURL, pass the user name and password using the -u cURL option.

curl -i -X GET -u username:password https://myhost:7001/opss/v2/keystore

For GET and DELETE methods, which do not send data in the request body, if a keystore or key is password-protected, you must pass the Base64-encrypted keystore and key passwords, respectively, in custom headers. For example:

curl -i -X DELETE -u username:password -H keystorePassword:cHdkMQ== -H keyPassword:bXlQd2Qy  https://myhost:7001/opss/v2/keystoreservice?"stripeName=myStripe&keystoreName=myKeystore"

Using HTTP Methods with OPSS REST

The OPSS REST endpoints support standard HTTP semantics.

REST Method	Task
`GET`	Retrieve information about the REST resource.
`POST`	Add a REST resource.
`PUT`	Update a REST resource.
`DELETE`	Delete a REST resource.

HTTP Status Codes for HTTP Methods

The HTTP methods used to manipulate the resources described in this section return one of the following HTTP status codes:

HTTP Status Code	Description
200 OK	The request was successfully completed. A 200 status is returned for successful `GET` or `POST` method.
201 Created	The request has been fulfilled and resulted in a new resource being created. The response includes a Location header containing the canonical URI for the newly created resource. A 201 status is returned from a synchronous resource creation or an asynchronous resource creation that completed before the response was returned.
202 Accepted	The request has been accepted for processing, but the processing has not been completed. The request may or may not eventually be acted upon, as it may be disallowed at the time processing actually takes place. When specifying an asynchronous (`__detached=true`) resource creation (for example, when deploying an application), or update (for example, when redeploying an application), a 202 is returned if the operation is still in progress. If `__detached=false`, a 202 may be returned if the underlying operation does not complete in a reasonable amount of time. The response contains a Location header of a job resource that the client should poll to determine when the job has finished. Also, returns an entity that contains the current state of the job
400 Bad Request	The request could not be processed because it contains missing or invalid information (such as, a validation error on an input field, a missing required value, and so on).
401 Unauthorized	The request is not authorized. The authentication credentials included with this request are missing or invalid.
403 Forbidden	The user cannot be authenticated. The user does not have authorization to perform this request.
404 Not Found	The request includes a resource URI that does not exist.
405 Method Not Allowed	The HTTP verb specified in the request (`DELETE`, `GET`, `POST`, `PUT`) is not supported for this request URI.
406 Not Acceptable	The resource identified by this request is not capable of generating a representation corresponding to one of the media types in the Accept header of the request. For example, the client's Accept header request XML be returned, but the resource can only return JSON.
415 Not Acceptable	The client's ContentType header is not correct (for example, the client attempts to send the request in XML, but the resource can only accept JSON).
500 Internal Server Error	The server encountered an unexpected condition that prevented it from fulfilling the request.
503 Service Unavailable	The server is unable to handle the request due to temporary overloading or maintenance of the server. The Oracle WSM REST web application is not currently running.