Using the REST API

Authentication

System Endpoints

Ping

This endpoint will return system information, like the current version and the system time. It is mostly used to see if your service is installed correctly.

Request

GET {baseUrl}/system/ping

Response:

HTTP/1.1 200 OK
Content-Length: {}
Content-Type: application/json; charset=utf-8

{
    "systemTime": "2022-05-10T15:00:00.000Z",
    "version": "2.0.5"
}

Rules Endpoints

List Rules

This endpoint will list all available rules.

Request

GET {baseUrl}/rules

Optional query parameters are skip and limit.

GET {baseUrl}/rules
    ?skip=0
    &limit=20

Response

HTTP/1.1 200 OK
Content-Length: {}
Content-Type: application/json; charset=utf-8

{
    "data": [
        {
            "connector": null,
            "destination": "https://somewhere.com/:id",
            "fallback": null,
            "id": 1,
            "pattern": "/documents/:id",
            "preserveQuery": true,
            "preserveHost": false,
            "redirect": true,
            "type": "lookup"
        }
    ],
    "limit": 20,
    "skip": 0
}

Possible Errors

Status Code	Error Code	Error Message	Description
400	invalid_pagination	e.g. 'skip'-field must be 0 or larger	The pagination parameters skip/limit are invalid.

Get a Rule

This endpoint will return a rule by its ID.

Request

GET {baseUrl}/rules/:id

Response

HTTP/1.1 200 OK
Content-Length: {}
Content-Type: application/json; charset=utf-8

{
    "connector": null,
    "destination": "https://somewhere.com/:id",
    "fallback": null,
    "id": 1,
    "pattern": "/documents/:id",
    "preserveQuery": true,
    "preserveHost": false,
    "redirect": true,
    "type": "lookup"
}

Possible Errors

Status Code	Error Code	Error Message	Description
400	missing_id	No ID specified	The id parameter was missing from the request.
404	unknown_entity	No rule with ID 'id' was found	The requested rule does not exist.

Create a Rule

This endpoint will create a new rule.

Request

POST {baseUrl}/rules

{ 
    "type": "rewrite",
    "pattern": "/documents/:id",
    "destination": "https://somewhere.com/:id",
    "redirect": true
}

Response

HTTP/1.1 201 Created
Content-Length: {}
Content-Type: application/json; charset=utf-8

{
    "connector": null,
    "destination": "https://somewhere.com/:id",
    "fallback": null,
    "id": 1,
    "pattern": "/documents/:id",
    "preserveQuery": false,
    "preserveHost": true,
    "redirect": true,
    "type": "lookup"
}

Possible Errors

Status Code	Error Code	Error Message	Description
400	missing_body	Missing request body	There was no request body with the request.
400	invalid_body	Request body must be an object	The request body was empty or not an object.
400	invalid_body	e.g. redirect must be a boolean value	Other validation errors that show what went wrong.
400	license_policy_error	Destination domain {domain} is not allowed by your license	Your license does not allow you to create a rule for this destination domain

Update a Rule

This endpoint will update an existing rule.

Note: a rule's ID cannot be updated.

Request

PUT {baseUrl}/rules/:id

{ 
    "type": "rewrite",
    "pattern": "/documents/:id",
    "destination": "https://somewhere.com/:id",
    "redirect": false
}

Response

HTTP/1.1 200 OK
Content-Length: {}
Content-Type: application/json; charset=utf-8

{
    "connector": null,
    "destination": "https://somewhere.com/:id",
    "fallback": null,
    "id": 2,
    "pattern": "/documents/:id",
    "preserveQuery": true,
    "preserveHost": false,
    "redirect": false,
    "type": "lookup"
}

Possible Errors

Status Code	Error Code	Error Message	Description
400	missing_id	No ID specified	The id parameter was missing from the request.
400	missing_body	Missing request body	There was no request body with the request.
400	update_id	Cannot update ID field	Update cannot update the ID of a rule.
404	unknown_entity	No rule with ID 'id' was found	The requested rule does not exist.
400	invalid_body	Request body must be an object	The request body was empty or not an object.
400	invalid_body	e.g. redirect must be a boolean value	Other validation errors that show what went wrong.

Delete a Rule

This endpoint will delete a rule by its ID. It will return a status code 204 regardless if the rule exists or not.

Request

DELETE {baseUrl}/rules/:id

Response

HTTP/1.1 204 No Content
Content-Type: application/json; charset=utf-8

Possible Errors

Status Code	Error Code	Error Message	Description
400	missing_id	No ID specified	The id parameter was missing from the request.

Migrations Endpoints

List Migrations

This endpoint will list all available migrations.

Request

GET {baseUrl}/migrations

Optional query parameters are skip and limit.

GET {baseUrl}/migrations
    ?skip=0
    &limit=20

Additionally, you can filter by connector, originalId and tags (separately or together).

GET {baseUrl}/migrations
    ?connector=filenet
    &originalId=636c8844-532c-4143-9600-7a2a281c9629

You can add a semi-colon (;) to filter with multiple tags. This filter will require all requested tags to be present.

GET {baseUrl}/migrations
    ?tags=dep-finance;folders

Response

HTTP/1.1 200 OK
Content-Length: {}
Content-Type: application/json; charset=utf-8

{
    "data": [
        { 
            "id": 1,
            "connector": "filenet",
            "originalId": "636c8844-532c-4143-9600-7a2a281c9629",
            "migrationId": "/media/press/logo.png",
            "tags": []
        }
    ],
    "limit": 20,
    "skip": 0
}

Possible Errors

Status Code	Error Code	Error Message	Description
400	invalid_pagination	e.g. 'skip'-field must be 0 or larger	The pagination parameters skip/limit are invalid.
400	invalid_query_param	e.g. 'originalId'-field must be a string	The given query parameter was invalid.

Get a Migration

This endpoint will return a migration by its ID.

Request

GET {baseUrl}/migrations/:id

Response

HTTP/1.1 200 OK
Content-Length: {}
Content-Type: application/json; charset=utf-8

{ 
    "id": 1,
    "connector": "filenet",
    "originalId": "636c8844-532c-4143-9600-7a2a281c9629",
    "migrationId": "/media/press/logo.png",
    "tags": []
}

Possible Errors

Status Code	Error Code	Error Message	Description
400	missing_id	No ID specified	The id parameter was missing from the request.
404	unknown_entity	No migration with ID 'id' was found	The requested migration does not exist.

Create a Migration

This endpoint will create a new migration.

Request

POST {baseUrl}/migrations

{ 
    "connector": "filenet",
    "originalId": "636c8844-532c-4143-9600-7a2a281c9629",
    "migrationId": "/media/press/logo.png",
}

Response

HTTP/1.1 201 Created
Content-Length: {}
Content-Type: application/json; charset=utf-8

{ 
    "id": 1,
    "connector": "filenet",
    "originalId": "636c8844-532c-4143-9600-7a2a281c9629",
    "migrationId": "/media/press/logo.png",
    "tags": []
}

Possible Errors

Status Code	Error Code	Error Message	Description
400	missing_body	Missing request body	There was no request body with the request.
400	invalid_body	Request body must be an object	The request body was empty or not an object.
400	invalid_body	e.g. connector must be a string value	Other validation errors that show what went wrong.

Update a Migration

This endpoint will update an existing migration.

Note: a migration's ID cannot be updated.

Request

PUT {baseUrl}/migrations/:id

{ 
    "connector": "filenet",
    "originalId": "636c8844-532c-4143-9600-7a2a281c9629",
    "migrationId": "/photos/press/logo.png",
    "tags": ["dep-finance"]
}

Additionally, you can update by filtering using connector and originalId (exclusively together).

PUT {baseUrl}/migrations
    ?connector=filenet
    &originalId=636c8844-532c-4143-9600-7a2a281c9629

{
    "migrationId": "/photos/press/something-else.png",
}

Response

HTTP/1.1 200 OK
Content-Length: {}
Content-Type: application/json; charset=utf-8

{ 
    "id": 1,
    "connector": "filenet",
    "originalId": "636c8844-532c-4143-9600-7a2a281c9629",
    "migrationId": "/photos/press/logo.png",
    "tags": ["dep-finance"]
}

Possible Errors

Status Code	Error Code	Error Message	Description
400	missing_id	No ID specified	The id parameter was missing from the request.
400	missing_body	Missing request body	There was no request body with the request.
400	update_id	Cannot update ID field	Update cannot update the ID of a migration.
404	unknown_entity	No rule with ID 'id' was found	The requested migration does not exist.
400	invalid_body	Request body must be an object	The request body was empty or not an object.
400	invalid_body	e.g. redirect must be a boolean value	Other validation errors that show what went wrong.
400	invalid_query_param	e.g. 'originalId'-field must be a string	The given query parameter was invalid.
400	missing_query_param	e.g. 'originalId'-field and 'connector'-field must be provided	One of the required query parameters was missing.

Delete a Migration

This endpoint will delete a migration by its ID. It will return a status code 204 regardless if the migration exists or not.

Request

DELETE {baseUrl}/migrations/:id

Response

HTTP/1.1 204 No Content
Content-Type: application/json; charset=utf-8

Possible Errors

Status Code	Error Code	Error Message	Description
400	missing_id	No id specified	The id parameter was missing from the request.