Services

This Public Stable API gets, creates, updates, or deletes services. To write services they must be in the “draft” state, which means they have not been provisioned. To provision changes made to services, use the Security Policy API.

Services API Methods

Functionality	HTTP	URI
Get a collection of services	GET	[api_version][org_href]/sec_policy/{pversion}/services
Get an individual service	GET	[api_version][org_href]/sec_policy/{pversion}/services/service_id
Create a new service	POST	[api_version][org_href]/sec_policy/draft/services
Update an individual service	PUT	[api_version][org_href]/sec_policy/draft/services/service_id
Delete an individual service	DELETE	[api_version][org_href]/sec_policy/draft/services/service_id

Active vs. Draft

This API operates on provisionable objects, which exist in either a draft (not provisioned) state or an active (provisioned) state.

Provisionable items include label groups, services, rulesets, IP lists, virtual services, firewall settings, enforcement boundaries, and virtual servers. For these objects, the URL of the API call must include the element called :pversion, which can be set to either draft or active.

Depending on the method, the API follows these rules: 

• For GET operations — :pversion can be draft, active, or the ID of the security policy.
• For POST, PUT, DELETE — :pversion can be draft (you cannot operate on active items) or the ID if the security policy.

Parameters

Parameter	Description	Type	Required
org_id	(GET, POST, PUT) Organization	Integer	Yes
description	Description of the service on which to filter. This parameter supports partial matches.	String	No
pversion	(GET, POST, PUT) Security Policy Version	String	Yes
service_id	Service ID. For GET [api_version][org_href]/sec_policy/{pversion}/services/service_id, PUT and DELETE	String	Yes
external_data_set	(GET, POST) The data source from which the resource originates. For example, if service information is stored in an external database.	String NULL	No
external_data_referenc	(GET, POST) A unique identifier within the external data source. For example, if service information is stored in an external database.	String NULL	No
max_results	(GET) The maximum number of results to return using GET. The maximum limit for returned services is 500. NOTE: If this parameter is not specified, or a value greater than 500 is specified, a maximum of 500 results are returned. To get more than 500 services, use an Asynchronous GET Collection.	Integer	No
name	Name of service on which to filter. This parameter supports partial matches.	String	GET: No POST: Yes
port	(GET, POST, PUT) Port on which to filter. This parameter supports partial matches. The range is from 1 to 65535. Enter -1 for any port.	String	No
proto	Transport Protocol	Integer	GET: No PUT, POST: Yes
to_port	(POST, PUT) High end of port range inclusive if specifying a range. If not specifying a range then don't send this.	Integer	No
icmp_type	ICMP Type (integer 0-255 for icmp protocol)	Integer	No
icmp_code	ICMP Code (integer 0-15 for icmp protocol)	Integer	No
max_results	(GET) The maximum number of results to return using GET. The maximum limit for returned services is 500. NOTE: If this parameter is not specified, or a value greater than 500 is specified, a maximum of 500 results are returned. To get more than 500 services, use an Asynchronous GET Collection.	Integer
process_name	(POST, PUT) Name of the process.	String	No
service_ports	(POST)
	id. Process ID of the service.	Integer	No
	port. Port number for the service.	Integer	Yes
	to_port. Destination port for the service.	Integer	Yes
	proto. Transport protocol to be used for the service.	Integer	Yes
windows_services	(POST)
	id: Process ID of the Windows service.	Integer	No
	port: Port number for the Windows service.	Integer	Yes
	to_port: Destination port for the Windows service.	Integer	Yes
	proto: Transport protocol used for the Windows service.	Integer	Yes
	service_name: Name of the Windows service.	String	No
	process_name: Name of the running Windows process.	String	No
external_data_set	(POST) The data source from which the resource originates. For example, if this service's information is stored in an external database.	String	No
external_data_reference	(POST) The external data reference from which the resource originates. For example, if this service's information is stored in an external database.	String	No

Get Services

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
      }
    ]
  }

Create a Service

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}]}' 

Update a Service

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}]}' 

Delete a Service

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