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 an individual service |
|
|
| Create a new service |
|
|
| Update an individual service |
|
|
| Delete an individual service |
|
|
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, 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 —
:pversioncan be draft, active, or the ID of the security policy. - For POST, PUT, DELETE —
:pversioncan be draft (you cannot operate on active items) or the ID if the security policy.
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]Query Parameters
Use the following optional query parameters to restrict the results of the query.
| Parameter | Description | Type |
|---|---|---|
external_data_set
|
The data source from which the resource originates. For example, if service information is stored in an external database. |
String |
external_data_reference
|
A unique identifier within the external data source. For example, if service information is stored in an external database. |
String |
name
|
Name of service on which to filter. This parameter supports partial matches. | String |
description
|
Description of the service on which to filter. This parameter supports partial matches. |
String |
port
|
Port on which to filter. This parameter supports partial matches. The range is from 1 to 65535. Enter -1 for any port. |
String |
proto
|
Protocol on which to filter. This parameter supports partial matches. | Integer |
max_results
|
The maximum number of results to return using GET. NOTE:
If this parameter is not specified, or a value greater than |
Integer |
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/servicesRequest Properties
| Property | Description | Type | Required |
|---|---|---|---|
name
|
Name of the service (does not need to be unique). | String | Yes |
description
|
Optional description for the service. | String | No |
process_name
|
Name of the process. | String | No |
service_ports
|
|||
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
|
|||
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
|
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
|
The external data reference from which the resource originates. For example, if this service's information is stored in an external database. |
String | Optional |
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