Activity Log API v1.0


Overview

The Activity Log API allows contract owners and administrators to discover what activity has happened under a specific contract. This allows auditing of user activities as well as changes to any resources. The activity is grouped by contract and can be refined using date ranges. Activity information is READ-ONLY so all calls made against the Activity Log API will be handled using GET requests.

You can consume the Activity Log API using the following endpoint:

URL Description
https://api.profitbricks.com/activitylog/v1/ Activity Log API Endpoint

The Activity Log API is secured using HTTP Basic Authentication in conjunction with SSL/TLS.

You will need to Base64 encode your credentials. Separate your username and password with a colon, i.e., username:password. Additional information and examples can be found in the Authorization section of the Cloud API - Getting Started documentation.

The Activity Log API is Swagger-enabled. You can quickly explore it by visiting the Swagger Online Demo and entering https://api.profitbricks.com/activitylog/v1/swagger.json in the box at the top of the page. Then press Explore to have the JSON file imported and parsed into an easily readable format.

Verify

This operation is used to confirm the API is available and returns version information.

Request

We can verify that the Activity Log API is accessible by sending a GET request to the API endpoint without any additional parameters.

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

The Authorization string contains your Base64 encoded account credentials.

Response

The response contains JSON-formatted data.

{
  "href": "string",
  "name": "Activity Log API",
  "version": "1.0"
}

Response Parameters

Name Description
href A reference URL.
name The Name of the API.
version The Version of the API.

CURL Example

The following shows how to submit the GET request using curl:

CURL Request

Just as a reminder, the --include parameter asks curl to return headers in the output. The --user parameter will encode the supplied credentials and provide the appropriate Authorization header containing the Base64 encoded credentials.

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
     https://api.profitbricks.com/activitylog/v1/

CURL Response

{
  "href" : "https://api.profitbricks.com/activitylog/v1/",
  "name" : "Activity Log API",
  "version" : "1.0"
}

Contracts

The next operation you will encounter with the Activity Log API is retrieving a list of contracts that your account credentials are authorized to access. This operation is primarily useful to ProfitBrick's Resellers, as a non-reseller user account will only have access to a single contract.

Request

The list of available contracts can be retrieved by sending a GET request to the endpoint plus /contracts.

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

The Authorization string contains your Base64 encoded reseller or account credentials.

Response

The response is a JSON array containing the list of contracts that you have access too.

[
  {
    "id": 0,
    "type": "string",
    "href": "string"
  }
]

Response Parameters

Name Description
id The Contract ID.
type A string indicating the type.
href A URL reference.

CURL Example

The following shows how to submit the GET request using curl:

Most versions of curl are able to automatically encode your credentials in the request header if you pass them in using the --user parameter.

CURL Request

curl --request GET \
     --user 'username@domain.tld:password' \
     https://api.profitbricks.com/activitylog/v1/contracts

CURL Response

If account credentials for a typical account that has access to one contract are used, then a single contractId will be returned:

[ {
  "id" : {contractId},
  "type" : "contracts",
  "href" : "https://api.profitbricks.com/activitylog/v1/contracts/{contractId}"
}

If you supply account credentials for a reseller account, or one that has access to multiple contracts, then multiple values for contractId will be returned:

[ {
  "id" : {contractId0},
  "type" : "contracts",
  "href" : "https://api.profitbricks.com/activitylog/v1/contracts/{contractId0}"
}
, {
  "id" : {contractId1},
  "type" : "contracts",
  "href" : "https://api.profitbricks.com/activitylog/v1/contracts/{contractId1}"
}
, {
  "id" : {contractId2},
  "type" : "contracts",
  "href" : "https://api.profitbricks.com/activitylog/v1/contracts/{contractId2}"
}
, {...

Contract Details

This operation returns the actual activity log data related to the specific contractId supplied in the request. The amount of data returned can be limited by providing one or both of the optional startDate and endDate parameters.

Request

The activity log for a specific contract can be retrieved by sending a GET request to the endpoint plus /contracts/{contractId}.

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

Request Parameters

It is possible to supply a start and/or end date as parameters to the request.

Parameter Name Description
dateStart A start date in the format (YYYY-MM-DD)
dateEnd An end date in the format (YYY-MM-DD)

Append the parameters to the request like this:

https://api.profitbricks.com/activitylog/v1/contracts/{contractID}?dateStart=2016-10-14&dateEnd=2016-10-15

If valid values for both dateStart and dateEnd are supplied, then the activity log information for the date range specified will be returned. Omitting either dateStart or dateEnd will return all entries available after dateStart or before dateEnd.

Response

The response may include a large quantity of JSON-formatted data. Lets examine a short response snippet.

In this example, a request has been made for a specific contract ID: 31721060. There were two "hits" returned containing event details however, we are looking at just the first returned event:

{
  "hits": {
    "total": 2,
    "hits": [
      {
        "_source": {
          "principal": {
            "sourceIP": "IP_ADDRESS",
            "identity": {
              "contractNumber": 31721060,
              "username": "username@domain.tld"
            },
            "sourceService": "UserWebservice"
          },
          "meta": {
            "auditVersion": "0.1",
            "time": "2016-09-23T12:02:52.394Z"
          },
          "event": {
            "param": {

            },
            "resources": [
              {
                "action": [
                  "sec.user.create"
                ],
                "id": "1466",
                "type": "user"
              }
            ],
            "type": "RequestAccepted"
          }
        }
      },

Response Parameters

The response consists of a JSON object containing a considerable amount of nested data. The first level, "hits", contains the following properties:

Name Type Description
total integer A count of total number of available activity events.

The next level is an array containing individual event objects. Each event object has a number of properties described in these tables:

Name Type Description
_source | object | The payload of a single activity event. |

_source contains three objects:

Name Type Description
principal object Primary details of the activity event.
meta object Meta information about the activity event.
event object Details specific to the activity event.

Each of these objects contains particular event data detailed below.

Principal

principal contains:

Name Type Description
sourceIP string The remote IP address which triggered the activity.
identity object The identity of the user who triggered the activity.
sourceService string The Ionos service used for performing the activity.

identity contains:

Name Type Description
contractNumber string The customer contract number.
username string The user name.

The sourceService string will contain one of the following values indicating which service was used to perform the logged activity:

Value Description
UserWebservice User Web Service - Called during inital contract creation and when payment data is updated.
ActivityLog_V1 Activity Log API v1
DCD Data Center Designer
PUBLIC_REST Cloud API Request Controller - Used by all versions of the Cloud API for handling "request status" operations.
PUBLIC_REST_V1 Cloud API v1
PUBLIC_REST_V2 Cloud API v2
PUBLIC_REST_V3 Cloud API v3
Reseller_V1 Reseller API v1

Meta

This object contains meta information about the event.

Name Type Description
auditVersion string The values returned is currently "0.1".
requestId string Identifier of the individual request which triggered the activity.
queueRefId integer Identifier of the provisioning queue reference. Use this value to group different events that were part of the same provisioning request.
time string Combined date and time of the activity event in UTC.
transactionId integer Identifier of the transaction which triggered the activity.

Event

This object contains details specific to the activity event. It contains the following properties:

Name Type Description
param object The value returned is currently "0.1".
resources array An array of resources affected by the givent activity.
message string Message explaining the current status of the request.
status string The current status of the request. [DONE, RUNNING, QUEUED, FAILED]
type string Type of the activity event. [Error, RequestAccepted, RequestStatusUpdate, Provision] Provisioning involves a sequence of these events types.

The param object contains:

Name Type Description
action string HTTP protocol method used to trigger the activity. [GET, POST, PATCH, PUT, DELETE]
error object Details of the error response returned for a given activity.
uri string HTTP URI for the given activity request.
initiator string Component which initiated the activity. Usually equivalent to sourceService in the principal section.
errorCode string Internal error code generated by the given activity.
sourceService string The source service for the activity. [Provisioning, PUBLIC_REST]

The error object under param contains these properties:

Name Type Description
httpStatus string HTTP error code for the given activity.
messages array An array of error messages corresponding to the given activity.

The messages array contains items ojbects with the following properties:

Name Type Description
errorCode string Internal error code generated by the given activity.
message string Details of the specific error generated by the given activity.

resources is an array of objects:

Name Type Description
action array A single action performed on the given resource. See table below for values.
id string Identifier of the given resource.
type string Type of the given resource. See table below for values.

action is an array of items containing a string describing the action that was performed on the resource. There are a large number of possible values returned here. Some example values are:

  • sec.user.create
  • ip.ipblock.reserve
  • vr.server.create
  • vr.firewall.activate
  • sn.snapshot.create

As you can see, the string provides a useful description so that you can determine what action was performed on the resource.

type will return a string with one of the following values:

Type Description
user User
group Group
contract Contract
datacenter Data Center
server Server
volume Volume
mount
imageMount
nic NIC
firewall Firewall
firewallrule Firewall Rule
lan LAN
loadbalancer Load Balancer
snapshot Snapshot
image Image
ipblock IP Block

CURL Example

The following shows how to submit the GET request using curl:

CURL Request

curl --request GET \
     --user 'username@domain.tld:password' \
     https://api.profitbricks.com/activitylog/v1/contracts/{contractId}

CURL Response

If you query a contractId that has no activity, the response will resemble this one:

{"hits": {"total":0}}

Since there is the potential of a large amount of data being returned when querying the Activity Log, it is recommended that you direct the output to a local file. Then the data can be further queried or manipulated using a number of different tools. We will demonstrate using a command-line utility, jq, in just a bit.

CURL Request with Optional Parameters

curl --request GET \
     --user 'username@domain.tld:password' \
     https://api.profitbricks.com/activitylog/v1/contracts/{contractId}?dateStart=2016-10-14&dateEnd=2016-10-16 > contractId_activity_20161014_20161016.json

CURL Response with Optional Parameters

The Activity Log data will be retrieved and stored in the local file contractId_activity_20161014_20161016.json

It is recommended that the --include parameter be omitted when using curl and redirecting the output into a file. That will prevent the HTTP response headers from being stored in the output file, as that will likely interfere with parsing the data using other tools.

Parsing the JSON Response

You may find the command-line utility jq useful in parsing the Activity Log data.

The jq Online Manual has helpful information and numerous examples on using jq. We will go through two examples here.

Additional information on jq is available in the jq wiki including a "Cookbook" section that demonstrates some things not found in the manual.

Retrieve a List of Contracts

In this example we will use curl and provide a set of reseller account credentials to return a list of available contracts. We will store the json data locally so that we can query it further.

curl --request GET  --user 'reseller@domain.tld:reseller_password' https://api.profitbricks.com/activitylog/v1/contracts > reseller_contracts.json

Here is an example of the first 20 lines of output stored in the file reseller_contracts.json:

head -20 reseller_contracts.json
[ {
  "id" : 31793781,
  "type" : "contracts",
  "href" : "https://api.profitbricks.com/activitylog/v1/contracts/31793781"
}
, {
  "id" : 31794402,
  "type" : "contracts",
  "href" : "https://api.profitbricks.com/activitylog/v1/contracts/31794402"
}
, {
  "id" : 31794416,
  "type" : "contracts",
  "href" : "https://api.profitbricks.com/activitylog/v1/contracts/31794416"
}
, {
  "id" : 31794420,
  "type" : "contracts",
  "href" : "https://api.profitbricks.com/activitylog/v1/contracts/31794420"
}

If we would rather have a list containing each id, one per line, we can use jq like this:

cat reseller_contracts.json | jq '.[].id'

or:

jq '.[].id' reseller_contracts.json

Which will return the output:

31793781
31794402
31794416
31794420
...

Filter Entries and Return a String of Relevant Data

In this example, we will retrieve Activity Log data and store it in a local file. Then we will use jq to filter the data looking for a specific sourceService, in this case, anything except "DCD". Once we have that, we will return a string of data consisting of the IP address, username, sourceService, and uri.

First retrieve the data using curl and store it locally in a file called activity_log_data.json. We will supply the optional dateStart parameter to the request to limit the size of the results a bit:

curl --request GET  --user 'reseller@domain.tld:reseller_password' https://api.profitbricks.com/activitylog/v1/contracts31764105?dateStart=2016-11-03 > activity_log_data.json

Once we have the JSON stored locally, we will utilize jq to filter it. Here is the command, and then we will explain it.

jq '.hits.hits[]._source | select(.principal.sourceService != "DCD") | "\(.principal.sourceIP) \(.principal.identity.username) \(.principal.sourceService) \(.event.param.uri)"' activity_log_data.json

The first part of the jq command, .hits.hits[]._source, iterates through the returned hits and returns the individual _source data. Then we use the jq select function to find items where sourceService is not equal to "DCD". The results of that are passed along and a string is constructed consisting of the IP address, username, sourceService, and uri.

We end up with output which can be copy/pasted, or redirected into a file for additional analysis.

"162.254.###.### username@domain.tld PUBLIC_REST_V2 https://api.profitbricks.com/rest/v2/datacenters?depth=5"
"208.115.###.### username01@domain.tld ActivityLog_V1 https://api.profitbricks.com/activitylog/v1/contracts"
"162.254.###.### username@domain.tld PUBLIC_REST_V2 https://api.profitbricks.com/rest/v2/datacenters?depth=5"
"208.115.###.### username01@domain.tld ActivityLog_V1 https://api.profitbricks.com/activitylog/v1/contracts/31764105?dateStart=2016-11-01"
"162.254.###.### username@domain.tld PUBLIC_REST_V2 https://api.profitbricks.com/rest/v2/datacenters?depth=5"
"208.115.###.### username01@domain.tld ActivityLog_V1 https://api.profitbricks.com/activitylog/v1/contracts/31764105?dateStart=2016-11-03"
"162.254.###.### username@domain.tld PUBLIC_REST_V2 https://api.profitbricks.com/rest/v2/datacenters?depth=5"

These two examples briefly demonstrate using jq to parse data available from the Activity Log. There are other tools and ways to parse JSON data besides jq. If you come up with something you find useful, please share it with the DevOps Central community.

Support

Please feel free to open a discussion related to the Activity Log API in the Community section of this site if you have any questions about using this API.