Difference between revisions of "TPS REST API"

From Dogtag
Jump to: navigation, search
(Overview)
(Overview)
Line 19: Line 19:
 
Authentication will be handled by Tomcat realm, but each resource may require specific authentication methods (e.g. anonymous, username/password, client certificate).
 
Authentication will be handled by Tomcat realm, but each resource may require specific authentication methods (e.g. anonymous, username/password, client certificate).
  
All users (operators, agents, administrators) will access the same resources, but depending on the access rights, some of the above operations might not be able to the user. The TPS service is responsible to determine if the user has the access right before executing the operation. Regardless, the client applications (CLI or Web UI) can still provide customized UI based for specific roles.
+
All users (operators, agents, administrators) will access the same resources, but depending on the access rights, some of the above operations might not be available to the user. The TPS service is responsible for determining if the user has the access right before executing the operation. Regardless, the client applications (CLI or Web UI) can still provide customized UI based for specific roles.
  
 
Some of the TPS operations will not be mapped into REST operations because the are purely used to generate the HTML page which is irrelevant for REST.
 
Some of the TPS operations will not be mapped into REST operations because the are purely used to generate the HTML page which is irrelevant for REST.

Revision as of 20:31, 25 June 2013

Overview

Dogtag will provide REST interface to manage TPS services as resources. A resource could also represent a collection of resources. Each resource will have a unique URL in this format:

  • Single resource: /tps/rest/<resource name>
  • Collection of resources: /tps/rest/<resource collection>/<resource ID>

Most of the TPS operations (eg. op=...) will be mapped into the following HTTP operations:

  • GET: searching resources or retrieving individual resource
  • POST: adding an object
  • PUT: modifying an object
  • DELETE: removing an object

These operations will return HTTP 200 (OK) return code upon successful operation. One exception is a successful add operation will return HTTP 201 (Created) and the URL of the newly created resource. Normal application errors will return HTTP 4xx return code. Unexpected server error will return HTTP 5xx return code.

Search operations may support paging. The server will return one page that contains a subset of the search result. The server will also return the total number of entries in the result. The client may request a specific page and also the number of entries per page.

The add and modify operations will return the updated object back, similar to the result of a GET operation. This way the client does not need to send another request to get the object after performing an update.

Authentication will be handled by Tomcat realm, but each resource may require specific authentication methods (e.g. anonymous, username/password, client certificate).

All users (operators, agents, administrators) will access the same resources, but depending on the access rights, some of the above operations might not be available to the user. The TPS service is responsible for determining if the user has the access right before executing the operation. Regardless, the client applications (CLI or Web UI) can still provide customized UI based for specific roles.

Some of the TPS operations will not be mapped into REST operations because the are purely used to generate the HTML page which is irrelevant for REST.

Tokens

Search tokens

The following TPS operations will be mapped into this REST operation:

  • op=search
  • op=view
  • op=search_admin
  • op=view_admin

Operation:

  • GET /tps/rest/tokens

Request:

  • Token ID
  • User ID
  • Page number (default: 1)
  • Page size (default: 20)

Response:

  • HTTP 200 OK
  • Result size
  • Tokens in the requested page:
    • Token ID
    • User ID
    • Status
    • Reason
    • Policy
    • Token type

Add token

The following TPS operations will be mapped into this REST operation:

  • op=add

Operation:

  • POST /tps/rest/tokens

Request:

  • Token ID

Response:

  • HTTP 201 Created
  • Location: <Token URL>

Get token

The following TPS operations will be mapped into this REST operation:

  • op=show: Display token details
  • op=show_admin: Display token details for admin
  • op=edit: Display token edit form

Operation:

  • GET /tps/rest/tokens/<Token ID>

Request:

  • Token ID

Response:

  • HTTP 200 OK
  • Token ID
  • User ID
  • Status
  • Reason
  • Policy
  • Token type
  • Key info
  • Applet ID
  • Date created
  • Date modified

Modify token

The following TPS operations will be mapped into this REST operation:

  • op=save: Save modification
  • op=do_confirm_token: Confirmation page to change token state
  • op=do_token: Mark token as physically damaged, permanently lost, temporarily lost, found, or terminated

Operation:

  • PUT /tps/rest/tokens/<Token ID>

Request:

  • Token ID
  • Number of modifications
  • Status
  • User ID
  • Policy
  • Reason
  • Action:
    • mark as physically damaged
    • mark as permanently lost
    • mark as temporarily lost
    • mark as found
    • mark as terminated

Response:

  • HTTP 200 OK
  • Token ID
  • User ID
  • Status
  • Reason
  • Policy
  • Token type
  • Key info
  • Applet ID
  • Date created
  • Date modified

Remove token

The following TPS operations will be mapped into this REST operation:

  • op=delete
  • op=confirm

Operation:

  • DELETE /tps/rest/tokens/<Token ID>

Request:

  • Token ID

Response:

  • HTTP 200 OK

Certificates

Search certificates

The following TPS operations will be mapped into this REST operation:

  • op=view_certificate
  • op=view_certificate_all

Operation:

  • GET /tps/rest/certificates

Request:

  • Token ID
  • User ID
  • Page number (default: 1)
  • Page size (default: 20)

Response:

  • HTTP 200 OK
  • Result size
  • Certificates in the requested page:
    • Certificate ID
    • Serial number
    • Subject
    • Token ID
    • Key type
    • Last status
    • User ID
    • Date modified

Get certificate

The following TPS operations will be mapped into this REST operation:

  • op=show_certificate

Operation:

  • GET /tps/rest/certificates/<Certificate ID>

Request:

  • Certificate ID (serial number?)

Response:

  • HTTP 200 OK
  • Certificate ID
  • Serial number
  • Subject
  • Token ID
  • Key type
  • Last status
  • User ID
  • Date modified

Activities

Search activities

The following TPS operations will be mapped into this REST operation:

  • op=view_activity
  • op=view_activity_all
  • op=view_activity_admin_all

Operation:

  • GET /tps/rest/users

Request:

  • Token ID
  • User ID
  • Page number (default: 1)
  • Page size (default: 20)

Response:

  • HTTP 200 OK
  • Activities in the requested page:
    • Activity ID
    • Token ID
    • IP
    • User ID
    • Operation
    • Result
    • Date created

Self Tests

Get self tests

The following TPS operations will be mapped into this REST operation:

  • op=self_test

Operation:

  • GET /tps/rest/selftests

Request:

  • Page number (default: 1)
  • Page size (default: 20)

Response:

  • HTTP 200 OK
  • Result size
  • Self tests in the requested page:
    • Enabled
    • Critical
    • Test ID

Run self tests

The following TPS operations will be mapped into this REST operation:

  • op=run_self_test

Operation:

  • POST /tps/rest/selftests

Request:

  • action = run

Response:

  • HTTP 200 OK
  • Status

Users

Search users

The following TPS operations will be mapped into this REST operation:

  • op=view_users

Operation:

  • GET /tps/rest/users

Request:

  • User ID
  • First name
  • Last name
  • Page number (default: 1)
  • Page size (default: 20)

Response:

  • HTTP 200 OK
  • Result size
  • Users in the requested page:
    • User ID
    • First name
    • Last name
    • Date created
    • Date modified

Add user

The following TPS operations will be mapped into this REST operation:

  • op=addUser

Operation:

  • POST /tps/rest/users

Request:

  • User ID
  • First name
  • Last name
  • Roles (operator, agent, admin)
  • Base-64 encoded user certificate
  • Profiles

Response:

  • HTTP 201 Created
  • Location: <User URL>
  • User ID
  • First name
  • Last name
  • Roles (operator, agent, admin)
  • Base-64 encoded user certificate
  • Profiles

Get user

The following TPS operations will be mapped into this REST operation:

  • op=edit_user

Operation:

  • GET /tps/rest/users/<User ID>

Request:

  • User ID

Response:

  • HTTP 200 OK
  • User ID
  • First name
  • Last name
  • Roles (operator, agent, admin)
  • Base-64 encoded user certificate
  • Profiles

Modify user

The following TPS operations will be mapped into this REST operation:

  • op=save_user
  • op=add_profile_user

Operation:

  • PUT /tps/rest/users/<User ID>

Request:

  • User ID
  • First name
  • Last name
  • Roles (operator, agent, admin)
  • Base-64 encoded user certificate
  • Profiles

Response:

  • HTTP 200 OK
  • User ID
  • First name
  • Last name
  • Roles (operator, agent, admin)
  • Base-64 encoded user certificate
  • Profiles

Remove user

The following TPS operations will be mapped into this REST operation:

  • op=do_delete_user
  • op=user_delete_confirm

Operation:

  • DELETE /tps/rest/users/<User ID>

Request:

  • User ID

Response:

  • HTTP 200 OK

Audit

Get audit configuration

The following TPS operations will be mapped into this REST operation:

  • op=audit_admin

Operation:

  • GET /tps/rest/audit

Request: None

Response:

  • HTTP 200 OK
  • Enable audit logging
  • Enable audit log signing
  • Audit log signing interval
  • Audit log signing buffer size
  • Events always logged
  • Optional events to be logged

Modify audit configuration

The following TPS operations will be mapped into this REST operation:

  • op=update_audit_admin

Operation:

  • PUT /tps/rest/audit

Request:

  • Enable audit logging
  • Enable audit log signing
  • Audit log signing interval
  • Audit log signing buffer size
  • Events always logged
  • Optional events to be logged

Response:

  • HTTP 200 OK
  • Enable audit logging
  • Enable audit log signing
  • Audit log signing interval
  • Audit log signing buffer size
  • Events always logged
  • Optional events to be logged

Profiles

Search profiles

Operation:

  • GET /tps/rest/profiles

Request:

  • Page number (default: 1)
  • Page size (default: 20)

Response:

  • HTTP 200 OK
  • Result size
  • Profiles in the requested page:
    • Profile ID

Add profile

Operation:

  • POST /tps/rest/profiles

Request:

  • Profile ID
  • Status
  • Contents

Response:

  • HTTP 201 Created
  • Location: <Profile URL>
  • Profile ID
  • Status
  • Contents

Get profile info

Operation:

  • GET /tps/rest/profiles/<Profile ID>

Request:

  • Profile ID

Response:

  • HTTP 200 OK
  • Profile ID
  • Status
  • Contents

Modify profile info

Operation:

  • PUT /tps/rest/profiles/<Profile ID>

Request:

  • Profile ID
  • Status
  • Contents

Response:

  • HTTP 200 OK
  • Profile ID
  • Status
  • Contents

Remove profile

Operation:

  • DELETE /tps/rest/profiles/<Profile ID>

Request:

  • Profile ID

Response:

  • HTTP 200 OK

Profile Mapping

Search profile mappings

Operation:

  • GET /tps/rest/profilemappings

Request:

  • Page number (default: 1)
  • Page size (default: 20)

Response:

  • HTTP 200 OK
  • Profile mappings in the requested page:
    • Profile Mapping ID

Add profile mapping

Operation:

  • POST /tps/rest/profilemappings

Request:

  • Profile Mapping ID
  • Status
  • Contents

Response:

  • HTTP 201 Created
  • Location: <Profile Mapping URL>
  • Profile Mapping ID
  • Status
  • Contents

Get profile mapping

Operation:

  • GET /tps/rest/profilemappings/<Profile Mapping ID>

Request:

  • Profile Mapping ID

Response:

  • HTTP 200 OK
  • Profile Mapping ID
  • Status
  • Contents

Modify profile mapping

Operation:

  • PUT /tps/rest/profilemappings/<Profile Mapping ID>

Request:

  • Profile Mapping ID
  • Status
  • Contents

Response:

  • HTTP 200 OK
  • Profile Mapping ID
  • Status
  • Contents

Remove profile mapping

Operation:

  • DELETE /tps/rest/profilemappings/<Profile Mapping ID>

Request:

  • Profile Mapping ID

Response:

  • HTTP 200 OK

Connections

Search connections

Operation:

  • GET /tps/rest/connections

Request:

  • Page number (default: 1)
  • Page size (default: 20)

Response:

  • HTTP 200 OK
  • Result size
  • Connections in the requested page:
    • Connection ID
    • Status
    • Contents

Add connection

Operation:

  • POST /tps/rest/connections

Request:

  • Connection ID
  • Status
  • Contents

Response:

  • HTTP 201 OK
  • Location: <Connection URL>
  • Connection ID
  • Status
  • Contents

Get connection

Operation:

  • GET /tps/rest/connections/<Connection ID>

Request:

  • Connection ID

Response:

  • HTTP 200 OK
  • Connection ID
  • Status
  • Contents

Modify connection info

Operation:

  • PUT /tps/rest/connections/<Connection ID>

Request:

  • Connection ID
  • Status
  • Contents

Response:

  • HTTP 200 OK
  • Connection ID
  • Status
  • Contents

Remove connection

Operation:

  • DELETE /tps/rest/connections/<Connection ID>

Request:

  • Connection ID

Response:

  • HTTP 200 OK

Authenticators

Search authenticators

Operation:

  • GET /tps/rest/authenticators

Request:

  • Page number (default: 1)
  • Page size (default: 20)

Response:

  • HTTP 200 OK
  • Result size
  • Authenticators in the requested page:
    • Authenticator ID
    • Status
    • Contents

Add authenticator

Operation:

  • POST /tps/rest/authenticators

Request:

  • Authenticator ID
  • Status
  • Contents

Response:

  • HTTP 200 OK
  • Location: <Authenticator URL>
  • Authenticator ID
  • Status
  • Contents

Get authenticator

Operation:

  • GET /tps/rest/authenticators/<Authenticator ID>

Request:

  • Authenticator ID

Response:

  • HTTP 200 OK
  • Authenticator ID
  • Status
  • Contents

Modify authenticator

Operation:

  • PUT /tps/rest/authenticators/<Authenticator ID>

Request:

  • Authenticator ID
  • Status
  • Contents

Response:

  • HTTP 200 OK
  • Authenticator ID
  • Status
  • Contents

Remove authenticator

Operation:

  • DELETE /tps/rest/authenticators/<Authenticator ID>

Request:

  • Authenticator ID

Response:

  • HTTP 200 OK

Configuration

Get configuration

The following TPS operations will be mapped into this REST operation:

  • op=add_config_parameter
  • op=edit_config_parameter
  • op=agent_select_config
  • op=agent_view_config
  • op=edit_config_parameter
  • op=return_to_edit_config_parameter
  • op=agent_select_config
  • op=select_config_parameter

Operation:

  • GET /tps/rest/config

Request: None

Response:

  • HTTP 200 OK
  • Contents

Modify configuration

The following TPS operations will be mapped into this REST operation:

  • op=delete_config_parameter
  • op=confirm_delete_config
  • op=agent_change_config_state
  • op=confirm_config_changes
  • op=save_config_changes

Operation:

  • PUT /tps/rest/config

Request:

  • Contents

Response:

  • HTTP 200 OK
  • Contents