REST API Developer Guide 22.2

This API gets all the services in your organization that are in the “draft” policy state (not yet provisioned).

By default, the maximum number returned on a GET collection of services is 500. To get more than 500 services, use an Asynchronous GET Collection.

URI to Get a Collection of Services

GET [api_version][org_href]/sec_policy/draft/services

URI to Get an Individual Service

GET [api_version][service_href]

Curl Command to Get All Services

curl -i -X GET https://pce.my-company.com:8443/api/v2/orgs/2/sec_policy/draft/services -H "Accept: application/json" -u $KEY:$TOKEN 

Curl Example to Get a Service

curl -i -X GET https://pce.my-company.com:8443/api/v2/orgs/2/sec_policy/draft/services/91 -H "Accept: application/json" -u $KEY:$TOKEN 

Response

Each individual service returned is identified by a service HREF. To GET, PUT, or DELETE an individual service, identify the service using its HREF in the API call.

{
   "href": "/orgs/2/sec_policy/draft/services/91",
   "created_at": "2015-09-02T08:42:02.299Z",
   "updated_at": "2015-09-02T08:42:02.299Z",
   "deleted_at": null,
   "created_by": {
     "href": "/users/4"
   },
   "updated_by": {
     "href": "/users/4"
   },
   "deleted_by": null,
   "name": "RabbitMQ",
   "description": "RabbitMQ",
   "description_url": null,
   "process_name": null,
   "service_ports": [
     {
       "port": 5672,
       "proto": "tcp"
     }
   ]
 },
 {
   "href": "/orgs/2/sec_policy/draft/services/77",
   "created_at": "2015-09-02T08:41:59.921Z",
   "updated_at": "2015-09-02T08:41:59.921Z",
   "deleted_at": null,
   "created_by": {
     "href": "/users/4"
   },
   "updated_by": {
     "href": "/users/4"
   },
   "deleted_by": null,
   "name": "PostgreSQL",
   "description": "PostgreSQL",
   "description_url": null,
   "process_name": null,
   "service_ports": [
     {
       "port": 5432,
       "proto": "tcp"
     }
   ]
 },
 {
   "href": "/orgs/2/sec_policy/draft/services/79",
   "created_at": "2015-09-02T08:42:00.315Z",
   "updated_at": "2015-09-02T08:42:00.315Z",
   "deleted_at": null,
   "created_by": {
     "href": "/users/4"
   },
   "updated_by": {
     "href": "/users/4"
   },
   "deleted_by": null,
   "name": "Tomcat",
   "description": "Tomcat",
   "description_url": null,
   "process_name": null,
   "service_ports": [
     {
       "port": 8080,
       "proto": "tcp"
     }
   ]
 },
{
    "href": "/orgs/7/sec_policy/active/services/878",
    "created_at": "2017-02-10T18:10:50.324Z",
    "updated_at": "2017-02-10T18:10:50.324Z",
    "deleted_at": null,
    "updated_by": null,
    "deleted_by": null,
    "name": "ICMP ECHO",
    "description": null,
    "description_url": null,
    "process_name": null,
    "service_ports": [
      {
        "icmp_type": 8,
        "icmp_code": null,
        "proto": 1
      },
      {
        "icmp_type": 128,
        "icmp_code": null,
        "proto": 58
      }
    ]
  }

This method creates an individual service. Once a service is created, it can be used to write rules for a security policy.

URI to Create a Service

POST [api_version][org_href]/sec_policy/draft/services

Example Payload

{
  "name": "RDP",
  "description": "Windows Remote Desktop",
  "service_ports": [
    {
      "port": 3389,
      "proto": 6
    }
  ]
}

Curl Command to Create Windows Service

This example shows how to create a Windows Remote Desktop (RDP) service.

curl -i -X POST https://pce.my-company.com:8443/api/v2/orgs/2/sec_policy/active/services -H "Content-Type:application/json" -u $KEY:$TOKEN -d '{"name":"RDP", "description":"Windows Remote Desktop","service_ports":[{"port":3389,"proto":6}]}' 

In order to update (PUT) an individual service, you need to know the HREF of the service you want to update. A service's HREF is returned when you get a collection of services from the PCE.

URI to Update an Individual Service

PUT [api_version][service_href]

Request Body

This example illustrates the request body you can pass to update a service, for example, to change the port used by the Nginx service from its current port number to 8080:

{
   "name": "nginx",
   "service_ports": [
     {
       "port": 8080,
       "proto": 6
     }
   ]
 }

Curl Command to Update Service

curl -i -X PUT https://pce.my-company.com:8443/api/v2/orgs/2/sec_policy/active/services/79 -H "Content-Type:application/json" -u $KEY:$TOKEN -d '{"name":"nginx","service_ports":[{"port":8080,"proto":6}]}' 

To delete an individual service, use the HREF of the service you want to delete, which is returned when you get a collection of services.

URI to Delete an Individual Service

DELETE [api_version][service_href]

Curl Command to Delete Service

curl -i -X DELETE https://pce.my-company.com:8443/api/v2/orgs/2/sec_policy/active/services/79 -u $KEY:$TOKEN