PerfOps Core API (1.0.0)

Download OpenAPI specification:Download

Introduction

This is the specification for the PerfOps Core API. This API is used to query PerfOps non-analytical data. This currently includes the following:

User Authentication
Locations - Countries, Regions, Cities
Nodes

You can view documentation for our analytics endpoints here.

Authentication

Authentication is through the Authorization HTTP header and accepts a bearer token. This token is a JWT obtained from the /auth endpoint.

The claims in the JWT include the following:

sub - The user's ID.
name - The user's full name.
email - The user's email address.
role - The user's role, eg. trial or admin
permissions - Specific custom permissions for the user.

The token will have a relatively short-lived expiry. You can refresh the token and request a new one prior to expiry with a POST to /auth/refresh with the current token as a the Bearer token. You will be issued an appropriate new token.

Pagination

All list endpoints are paginated, the pagination is controlled with querystring parameters page and perPage to specify the page to fetch and how many records should be fetched per page. The pagination metadata will return the total number of results across all pages that match the current filters.

Filtering

All list endpoints should support filtering. The wireframes do not specify which columns should be filtered on and ultimately the limit on these will be database indexes and what we can efficiently query.

Filtering will be done by specifying query parameters for the name of the field and if relevant, comma separated values.

eg.

GET /countries?name=United+Kingdom
GET /countries?code=GB,DE,US

Ordering

Ordering is available on most endpoints, the querystring parameters to use are order and direction. order should be the field to order by and direction should be either asc or desc.

eg.

GET /countries?order=name&direction=asc

General

Endpoints that don't belong in other categories.

Ping

Returns basic information about the API and the current user. This will include your IP address, the API timestamp and the version.

Authorizations:

None

Responses

Response samples

200

Content type

application/json

{"timestamp": "2023-10-03T14:41:31+00:00",
"version": "1.0.0",
"ip": "127.0.0.1"
}

Auth

Authenticates a user's credentials and returns a valid token on success.

If the user has 2FA enabled on their account, you will need to provide a one-time-password in the otp field.

If you do not provide this, and the user has 2FA enabled, you will get a 422 response for the otp field.

Authorizations:

None

Request Body schema: application/json

username required	string The username for the user
password required	string The password for the user
otp	string A one-time password for the user, usually from the 2FA.

Responses

Request samples

Payload

Content type

application/json

{"username": "bob@example.com",
"password": "hunter2",
"otp": 123456
}

Response samples

200
401
422

Content type

application/json

{"data": {"token": "eyJhbGciOiJSUzI1NiJ9.eyJhY2NvdW50SWQiOjEwMDEsInNvdXJjZUlwIjoiMDowOjA6MDowOjA6MDoxIiwidXNlcklkIjoxMDAwLCJzdWIiOiJqZG9lIiwiaWF0IjoxNjg1NTM5MjE4LCJleHAiOjE2ODU1NDI4MTh9.CbDsDQlJLMqKTbPsE-hpq1x6KuGUkOehZsz_igevVQ1_7ccM-SQy4fAtJKOaTMGpKAyeJMjD-_z4GZWXqOR8lRoLbAmg2mDnCIjqf6MqdnK_tQ5QA3e3gFykM-AP0cITeehEvqHVZnKwGlZ4E2BMOVSZ8i3WC2Wk80XE6HLSj6qYeuanTxipSFF84C1nxUD0-AXbJ9rqhw74sECMJOtWkXyz33BUnTiroN8u1AwPa_TiI9sAwzRIxaNWHs-LsIAo6_hg_Hl2Z5ym7rq-hl08jKF-rpx1L4zwZgl4GvGLBSBs-hh2Ng8uuGmSp3pvbSsGw_BJ7RuvvLjORRX3o8UNIw",
"tokenExpiresAt": "2023-10-03T14:41:31+00:00",
"user": {"id": 7665,
"email": "team@perfops.net",
"createdAt": "2023-10-03T14:41:31+00:00",
"role": "trial",
"permissions": ["client-dns-access"
]
}
}
}

Refresh Auth Token

Fetches a new JWT with an updated expiry

Authorizations:

bearerAuth

Responses

Response samples

200
401

Content type

application/json

{"data": {"token": "eyJhbGciOiJSUzI1NiJ9.eyJhY2NvdW50SWQiOjEwMDEsInNvdXJjZUlwIjoiMDowOjA6MDowOjA6MDoxIiwidXNlcklkIjoxMDAwLCJzdWIiOiJqZG9lIiwiaWF0IjoxNjg1NTM5MjE4LCJleHAiOjE2ODU1NDI4MTh9.CbDsDQlJLMqKTbPsE-hpq1x6KuGUkOehZsz_igevVQ1_7ccM-SQy4fAtJKOaTMGpKAyeJMjD-_z4GZWXqOR8lRoLbAmg2mDnCIjqf6MqdnK_tQ5QA3e3gFykM-AP0cITeehEvqHVZnKwGlZ4E2BMOVSZ8i3WC2Wk80XE6HLSj6qYeuanTxipSFF84C1nxUD0-AXbJ9rqhw74sECMJOtWkXyz33BUnTiroN8u1AwPa_TiI9sAwzRIxaNWHs-LsIAo6_hg_Hl2Z5ym7rq-hl08jKF-rpx1L4zwZgl4GvGLBSBs-hh2Ng8uuGmSp3pvbSsGw_BJ7RuvvLjORRX3o8UNIw",
"tokenExpiresAt": "2023-10-03T14:41:31+00:00",
"user": {"id": 7665,
"email": "team@perfops.net",
"createdAt": "2023-10-03T14:41:31+00:00",
"role": "trial",
"permissions": ["client-dns-access"
]
}
}
}

Locations

Endpoints related to locations.

List Countries

Fetches a paginated list of Countries

Authorizations:

bearerAuth

query Parameters

page	integer Default: 1 The page of results to fetch
perPage	integer Default: 50 The number of results per page

Responses

Response samples

200
401

Content type

application/json

{"items": [{"code": "GB",
"name": "United Kingdom",
"longitude": -2,
"latitude": 54,
"region": {"id": 10,
"name": "Western Europe",
"longitude": 7.297035,
"latitude": 47.719001
}
}
],
"pagination": {"total": 23,
"count": 3,
"perPage": 50,
"currentPage": 1,
"totalPages": 1
},
"links": {"self": "https://core-api.perfops.net/v1/countries?page=3",
"first": "https://core-api.perfops.net/v1/countries?page=1",
"last": "https://core-api.perfops.net/v1/countries?page=5",
"previous": "https://core-api.perfops.net/v1/countries?page=2",
"next": "https://core-api.perfops.net/v1/countries?page=4"
}
}

Get Country

Fetches a single country

Authorizations:

bearerAuth

path Parameters

country

required

string

Examples: GB

ISO 3166 country code

Responses

Response samples

200
401
404

Content type

application/json

{"data": {"code": "GB",
"name": "United Kingdom",
"longitude": -2,
"latitude": 54,
"region": {"id": 10,
"name": "Western Europe",
"longitude": 7.297035,
"latitude": 47.719001
}
},
"links": {"self": "https://core-api.perfops.net/v1/countries/GB",
"region": "https://core-api.perfops.net/v1/regions/10",
"cities": "https://core-api.perfops.net/v1/cities?country=GB"
}
}

List Regions

Fetches a paginated list of regions

Authorizations:

bearerAuth

query Parameters

page	integer Default: 1 The page of results to fetch
perPage	integer Default: 50 The number of results per page

Responses

Response samples

200
401

Content type

application/json

{"items": [{"id": 10,
"name": "Western Europe",
"longitude": 7.297035,
"latitude": 47.719001
}
],
"pagination": {"total": 23,
"count": 3,
"perPage": 50,
"currentPage": 1,
"totalPages": 1
},
"links": {"self": "https://core-api.perfops.net/v1/countries?page=3",
"first": "https://core-api.perfops.net/v1/countries?page=1",
"last": "https://core-api.perfops.net/v1/countries?page=5",
"previous": "https://core-api.perfops.net/v1/countries?page=2",
"next": "https://core-api.perfops.net/v1/countries?page=4"
}
}

Get Region

Fetches a single region

Authorizations:

bearerAuth

path Parameters

region

required

integer

Examples: 10

ID of the region

Responses

Response samples

200
401
404

Content type

application/json

{"data": {"id": 10,
"name": "Western Europe",
"longitude": 7.297035,
"latitude": 47.719001
},
"links": {"self": "https://core-api.perfops.net/v1/regions/10"
}
}

List Cities

Fetches a paginated list of Cities

Authorizations:

bearerAuth

query Parameters

page	integer Default: 1 The page of results to fetch
perPage	integer Default: 50 The number of results per page

Responses

Response samples

200
401

Content type

application/json

{"items": [{"id": 17320,
"name": "London",
"longitude": -0.12574,
"latitude": 51.50853,
"country": {"code": "GB",
"name": "United Kingdom",
"longitude": -2,
"latitude": 54,
"region": {"id": 10,
"name": "Western Europe",
"longitude": 7.297035,
"latitude": 47.719001
}
}
}
],
"pagination": {"total": 23,
"count": 3,
"perPage": 50,
"currentPage": 1,
"totalPages": 1
},
"links": {"self": "https://core-api.perfops.net/v1/countries?page=3",
"first": "https://core-api.perfops.net/v1/countries?page=1",
"last": "https://core-api.perfops.net/v1/countries?page=5",
"previous": "https://core-api.perfops.net/v1/countries?page=2",
"next": "https://core-api.perfops.net/v1/countries?page=4"
}
}

Get City

Fetches a single city

Authorizations:

bearerAuth

path Parameters

city

required

number

Examples: 17320

ID for the city

Responses

Response samples

200
401
404

Content type

application/json

{"data": {"id": 17320,
"name": "London",
"longitude": -0.12574,
"latitude": 51.50853,
"country": {"code": "GB",
"name": "United Kingdom",
"longitude": -2,
"latitude": 54,
"region": {"id": 10,
"name": "Western Europe",
"longitude": 7.297035,
"latitude": 47.719001
}
}
},
"links": {"self": "https://core-api.perfops.net/v1/cities/17320",
"country": "https://core-api.perfops.net/v1/countries/GB",
"region": "https://core-api.perfops.net/v1/regions/10"
}
}

Nodes

Endpoints related to nodes.

List Nodes

Fetches a paginated list of Nodes.

You can specify an Accept: text/plain header to review just the IP addresses for nodes matching your filter. This will not be paginated. As a shortcut you can also just request /nodes.txt to get this text response as well.

Authorizations:

None

query Parameters

page	integer Default: 1 The page of results to fetch
perPage	integer Default: 50 The number of results per page
country	string Examples: country=GB country=GB,US An optional list of comma-separated ISO 3166 country codes to filter by.
city	string Examples: city=154 city=154,32 An optional comma-separated list of city IDs to filter by
region	string Examples: region=154 region=154,32 An optional comma-separated list of region IDs to filter by
order	string Enum: "id" "city" "country" "region" Optional column to order by - defaults to `id`.

Responses

Response samples

200

Content type

application/json

{"items": [{"id": 412,
"city": {"id": 17320,
"name": "London",
"longitude": -0.12574,
"latitude": 51.50853
},
"country": {"code": "GB",
"name": "United Kingdom",
"longitude": -2,
"latitude": 54
},
"region": {"id": 10,
"name": "Western Europe",
"longitude": 7.297035,
"latitude": 47.719001
},
"ipv4": "127.0.0.1",
"ipv6": "::1"
}
],
"pagination": {"total": 23,
"count": 3,
"perPage": 50,
"currentPage": 1,
"totalPages": 1
},
"links": {"self": "https://core-api.perfops.net/v1/countries?page=3",
"first": "https://core-api.perfops.net/v1/countries?page=1",
"last": "https://core-api.perfops.net/v1/countries?page=5",
"previous": "https://core-api.perfops.net/v1/countries?page=2",
"next": "https://core-api.perfops.net/v1/countries?page=4"
}
}

Get Node

Fetches a single node

Authorizations:

None

path Parameters

node

required

integer

Examples: 412

The unique ID for the node

Responses

Response samples

200
404

Content type

application/json

{"data": {"id": 412,
"city": {"id": 17320,
"name": "London",
"longitude": -0.12574,
"latitude": 51.50853
},
"country": {"code": "GB",
"name": "United Kingdom",
"longitude": -2,
"latitude": 54
},
"region": {"id": 10,
"name": "Western Europe",
"longitude": 7.297035,
"latitude": 47.719001
},
"ipv4": "127.0.0.1",
"ipv6": "::1"
},
"links": {"self": "https://core-api.perfops.net/v1/nodes/412",
"city": "https://core-api.perfops.net/v1/cities/10",
"country": "https://core-api.perfops.net/v1/countries/GB",
"region": "https://core-api.perfops.net/v1/regions/4"
}
}