Endpoints in the BMC Digital Workplace Catalog REST API
You can perform the following actions by using the supported API categories in the BMC Digital Workplace Catalog:
Authentication
Within the Digital Workplace Catalog, users with the role permissions of asset manager and service catalog admin can see all services. The same users in external systems that link to Digital Workplace Catalog have the same access permissions. This support is expected to be removed in the future, where Digital Workplace Catalog will manage role permissions completely independently from the external system.
To request authentication token
Method | Endpoint |
---|---|
POST | /users/login |
Parameters
Name | Where | Type | Required | Default | Example | Description |
---|---|---|---|---|---|---|
id | body | string | ![]() | none | <your_user> | Digital Workplace Catalog user login account (with organization domain). |
password | body | string | ![]() | none | <your_password> | Password |
Example request body
{
"id": "<your_user>",
"password": "<your_password>"
}
Response
Response | Value | Notes |
---|---|---|
HTTP code | 200 | Application returns an authentication token that is valid for about half an hour. |
Error handling
Failed authentication requests return an error object with the following properties.
Name | Type | Description |
---|---|---|
message | string | Error message with error code. |
data | string | Error message description. |
Categories
To retrieve a full category list
Method | URL |
---|---|
GET | /categories |
Parameters
Name | Where | Type | Required | Default | Example | Description |
---|---|---|---|---|---|---|
perPage | query | integer | No | -1 | 20 | Page size. -1 for non-paginated search. |
page | query | integer | No | 1 | 1 | Page number |
Response
Response | Value | Notes |
---|---|---|
HTTP code | 200 | Returns a category list object array. |
type | application/json | Not applicable. |
{
"pageSize": 5,
"page": 1,
"categories": [
{
"id": "000000000000001",
"guid": "AGGADG1AANVNMAOBXYYOAAAASGWDVD",
"name": "Accounts, Security, and IDs",
"categoryGroupId": "000000000000001",
"parentId": null,
"childCount": 5,
"subCategories": null
},
{
"id": "000000000000002",
"guid": "AGGADG1AANVNMAOBXYYOAAAASGWDVE",
"name": "User accounts and account access",
"categoryGroupId": "000000000000001",
"parentId": "000000000000001",
"childCount": 0,
"subCategories": null
},
{
"id": "000000000000003",
"guid": "AGGADG1AANVNMAOBXYYOAAAASGWDVF",
"name": "System accounts",
"categoryGroupId": "000000000000001",
"parentId": "000000000000001",
"childCount": 0,
"subCategories": null
},
{
"id": "000000000000004",
"guid": "AGGADG1AANVNMAOBXYYOAAAASGWDVG",
"name": "Access requests",
"categoryGroupId": "000000000000001",
"parentId": "000000000000001",
"childCount": 0,
"subCategories": null
},
{
"id": "000000000000005",
"guid": "AGGADG1AANVNMAOBXYYOAAAASGWDVH",
"name": "IDs, badges, and facility access",
"categoryGroupId": "000000000000001",
"parentId": "000000000000001",
"childCount": 0,
"subCategories": null
}
],
"total": 123
}
Response properties
Name | Type | Description |
---|---|---|
pageSize | integer | Pass through request parameter. |
page | integer | Pass through request parameter. |
categories | array | Category object array. |
Error handling
Failed requests return an error object with the following properties.
Argument | Type | Description |
---|---|---|
message | string | Error message with error code. |
To retrieve descendants of a given category
This API returns only categories that contain services that are entitled to the requesting user.
Method | Endpoint |
---|---|
GET | /categories/{categoryId}/categories |
Parameters
Name | Where | Type | Required | Default | Example | Description |
---|---|---|---|---|---|---|
categoryId | URL | Yes | None | 000000000000001 | Category ID to retrieve. | |
depth | query | int | No | 1 | 2 | Depth of the category being retrieved. Allowed values: 1, 2, 3. |
requestedfor | query | String | No | None | Mary | When a user is specified, the entitlement check is performed against the user. Otherwise, entitlement is checked on the current user. |
Response
Response | Value | Notes |
---|---|---|
HTTP code | 200 | Returns a category array object. If the requested categoryId does not exist, or does not contain descendants, then an empty array is returned. |
type | application/json | Not applicable. |
[
{
"id": "000000000000002",
"guid": null,
"name": "User accounts and account access",
"categoryGroupId": "000000000000001",
"parentId": "000000000000001",
"childCount": 0,
"subCategories": null
},
{
"id": "000000000000003",
"guid": null,
"name": "System accounts",
"categoryGroupId": "000000000000001",
"parentId": "000000000000001",
"childCount": 0,
"subCategories": null
},
{
"id": "000000000000004",
"guid": null,
"name": "Access requests",
"categoryGroupId": "000000000000001",
"parentId": "000000000000001",
"childCount": 0,
"subCategories": null
},
{
"id": "000000000000005",
"guid": null,
"name": "IDs, badges, and facility access",
"categoryGroupId": "000000000000001",
"parentId": "000000000000001",
"childCount": 0,
"subCategories": null
},
{
"id": "000000000000006",
"guid": null,
"name": "Remote access",
"categoryGroupId": "000000000000001",
"parentId": "000000000000001",
"childCount": 0,
"subCategories": null
}
]
Response properties
Name | Type | Description |
---|---|---|
id | string | Category ID used by the application. |
guid | string | Unique ID used by the platform. |
name | string | Category name. |
categoryGroupId | string | Group to which the category belongs. Currently there is only one category group, referenced as "Type of service". |
parentId | string | ID of child's parent category(?) or, if no child, null. |
childCount | integer | Number of direct descendant categories. |
subCategories | string | Null |
Error handling
Failed requests return an error object with the following properties.
Argument | Type | Description |
---|---|---|
message | string | Error message with the error code. |
To retrieve category groups
Method | Endpoint |
---|---|
GET | /categories/groups |
Parameters
None
Response
Response | Value | Notes |
---|---|---|
HTTP code | 200 | Successfulful returns category array. |
type | application/json | Not applicable. |
[
{
"id": "000000000000001",
"guid": "AGGADG1AANVNMAOBXYYOAAAASGWDVC",
"name": "Type of Service",
"description": "",
"systemId": "type-of-service",
"groupStatus": "ACTIVE",
"childCount": 18,
"categories": null
}
]
Response properties
Name | Type |
---|---|
id | string |
guid | string |
name | string |
description | string |
systemId | string |
groupStatus | string |
childCount | integer |
categories | string |
Error handling
Failed requests return an error object with the following properties.
Argument | Type | Description |
---|---|---|
message | string | Error message with error code. |
To retrieve categories of a given category group
Method | Endpoint |
---|---|
GET | /categories/groups/{categoryGroupId}/categories |
Parameters
Name | Where | Type | Required | Default | Example | Description |
---|---|---|---|---|---|---|
categoryGroupId | URL | Yes | Not applicable. | |||
depth | body | integer | No | 1 | 2 | Depth of the cateogory being retrieved. Allowed values: 1,2,3 |
requestedfor | query | String | No | Mary | When a user is specified, the entitlement check is performed against the user. Otherwise, entitlement is checked on the current user. |
Response
Response | Value | Notes |
---|---|---|
HTTP code | 200 | Successful response returns array of category objects. |
type | application/json | Not applicable. |
[
{
"id": "000000000000002",
"guid": null,
"name": "User accounts and account access",
"categoryGroupId": "000000000000001",
"parentId": "000000000000001",
"childCount": 0,
"subCategories": null
},
{
"id": "000000000000003",
"guid": null,
"name": "System accounts",
"categoryGroupId": "000000000000001",
"parentId": "000000000000001",
"childCount": 0,
"subCategories": null
},
{
"id": "000000000000004",
"guid": null,
"name": "Access requests",
"categoryGroupId": "000000000000001",
"parentId": "000000000000001",
"childCount": 0,
"subCategories": null
},
{
"id": "000000000000005",
"guid": null,
"name": "IDs, badges, and facility access",
"categoryGroupId": "000000000000001",
"parentId": "000000000000001",
"childCount": 0,
"subCategories": null
},
{
"id": "000000000000006",
"guid": null,
"name": "Remote access",
"categoryGroupId": "000000000000001",
"parentId": "000000000000001",
"childCount": 0,
"subCategories": null
}
]
Error handling
Failed requests return an error object with the following properties:
Argument | Type | Description |
---|---|---|
message | string | Error message with error code. |
Services
To retrieve details of a single service item
Method | Endpoint |
---|---|
GET | /services/{serviceId} |
Parameters
Name | Where | Type | Required | Example | Description |
---|---|---|---|---|---|
serviceId | URL | Yes | Not applicable. | ||
requestedfor | query parameter | String | No | Mary | When a user is specified, the entitlement check is performed against the user. Otherwise, entitlement is checked on the current user. |
Response
Response | Value |
---|---|
HTTP code | 200 |
type | application/json |
{
"serviceType": "Desktop",
"templateType": "SERVICE",
"id": "000000000001219",
"name": "Adobe Illustrator",
"description": "<p>Although during its first decade Adobe developed Illustrator primarily for Macintosh, it .....",
"iconUrl": "/mp/media/.........0IjoicG5nIn1dXQ/file.png?sha=d706a107dc3d5cc6",
"rating": 0.8,
"modifiedDate": "2016-01-27T13:46:17.000+0000",
"createdDate": "2016-01-27T13:38:50.000+0000",
"ratingCount": 2,
"supplier": {
"id": "000000000000001",
"name": "Coke Services"
},
"categories": [
{
"id": "000000000000041",
"name": "Computer software",
"categoryGroupId": "000000000000001",
"parentId": null,
"childCount": 0,
"subCategories": null
},
{
"id": "000000000000047",
"name": "Graphics and design",
"categoryGroupId": "000000000000001",
"parentId": "000000000000041",
"childCount": 0,
"subCategories": null
}
],
"price": {
"paymentType": "Once",
"currency": "USD"
},
"onceCost": 120,
"monthlyCost": 0,
"yearlyCost": 0,
"dynamicFields": [
{
"title": "Platform",
"content": "Windows",
"documents": []
}
],
"bundledServices": [],
"entitled": true,
"media": [
{
"type": "IMAGE",
"url": "/mp/media/......../file.jpg?sha=0d05cab032f35a0b"
},
{
"type": "IMAGE",
"url": "/mp/media/......../file.jpg?sha=a70919ad560b236a"
},
{
"type": "IMAGE",
"url": "/mp/media/......../file.jpg?sha=adf9a4581061ead9"
},
{
"type": "VIDEO",
"url": "https://www.youtube.com/watch?v=d0LTzbksUiU"
}
]
}
Error handling
Failed requests return an error object with the following properties.
Argument | Type | Description |
---|---|---|
message | string | Error message with error code. |
To search for services
Search criteria can be by serviceIds, categoryId, or free text for a single service name or tag.
Note
Multiple search criteria cannot be used in a same call. Wildcards are also not supported.
{
"serviceIds": ["%123%","%456","789%"],
"title": "apple"
}
Method | Endpoint |
---|---|
POST | /services/search |
Parameters
Name | Where | Type | Required | Default | Example | Description |
---|---|---|---|---|---|---|
perPage | query | integer | No | -1 | 20 | Page size. -1 for non-paginated search. |
page | query | integer | No | 1 | 1 | Page number to display. |
serviceIds | body | string | No | Not applicable. | ||
categoryId | body | string | No | Not applicable. | ||
title | body | string | No | Not applicable. | ||
requestedfor | query | String | No | Mary | When a user is specified, the entitlement check is performed against the user. Otherwise, entitlement is checked on the current user. |
{}
{"serviceIds": ["123","456","789"]}
{"title": "apple"}
{"categoryId": "111"}
Response
Response | Value | Notes |
---|---|---|
HTTP code | 200 | Successful response receives an array of service objects. |
type | application/json |
{
"services": [
{
"serviceType": "Cloud Software 1",
"templateType": "SERVICE",
"id": "000000000000101",
"name": "Office 365",
"excerpt": "Get the most secure Office for your business",
"iconUrl": "/mp/media/.../file.png?sha=b63f635628db7722",
"rating": 0,
"modifiedDate": "2015-12-03T18:43:35.000+0000",
"createdDate": "2015-12-03T18:35:48.000+0000",
"ratingCount": 0,
"categories": [
{
"id": "000000000000138",
"name": "Collaboration tools",
"categoryGroupId": "000000000000002",
"parentId": "000000000000135",
"childCount": 0,
"subCategories": null
},
{
"id": "000000000000141",
"name": "Productivity",
"categoryGroupId": "000000000000002",
"parentId": "000000000000135",
"childCount": 0,
"subCategories": null
}
],
"price": {
"paymentType": "Recurring",
"currency": "USD",
"paymentSchedule": "Monthly"
},
"onceCost": 0,
"monthlyCost": 8.25,
"yearlyCost": 99,
"provisioningTime": {
"type": "ProvisioningTimeMetric",
"value": 30,
"timeUnit": "MIN"
},
"bundledServices": [],
"entitled": true
},
{
"serviceType": "Cloud Software 1",
"templateType": "SERVICE",
"id": "000000000000108",
"name": "Evernote Premium",
"excerpt": "Evernote Premium unites writing, collection, discussion, and presentation in a single workspace. Instead of jumping between apps, keep focus in one place and your best work will follow.",
"iconUrl": "/mp/media/..../file.png?sha=54ce415746fe5a0d",
"rating": 0,
"modifiedDate": "2015-12-04T01:43:03.000+0000",
"createdDate": "2015-12-03T20:04:32.000+0000",
"ratingCount": 0,
"categories": [
{
"id": "000000000000164",
"name": "Computer software",
"categoryGroupId": "000000000000002",
"parentId": null,
"childCount": 0,
"subCategories": null
},
{
"id": "000000000000167",
"name": "Collaboration tools",
"categoryGroupId": "000000000000002",
"parentId": "000000000000164",
"childCount": 0,
"subCategories": null
},
{
"id": "000000000000166",
"name": "Business",
"categoryGroupId": "000000000000002",
"parentId": "000000000000164",
"childCount": 0,
"subCategories": null
}
],
"price": {
"paymentType": "Recurring",
"currency": "USD",
"paymentSchedule": "Yearly"
},
"onceCost": 0,
"monthlyCost": 4.17,
"yearlyCost": 49.99,
"bundledServices": [],
"entitled": true
}
],
"pageSize": 10
"page": 1,
"total": 2
}
Error handling
Failed requests return an error object with the following properties:
Argument | Type | Description |
---|---|---|
message | string | Error message with error code. |
To retrieve the full catalog view setting of ON or OFF
Method | Endpoint |
---|---|
GET | /services/fullcatalogview |
Parameters
None
Response
Response | Value | Notes |
---|---|---|
HTTP code | 200 | Successful response returns a boolean value. true = ON, false = OFF. |
type | application/json | Not applicable. |
true
false
Error handling
Failed requests return an error object with the following properties.
Argument | Type | Description |
---|---|---|
message | string | Error message with error code. |
Requests and questions
To initiate a request for a service by ID
Method | Endpoint |
---|---|
POST | /services/{serviceId}/requests |
Parameters
Name | Where | Type | Required | Default | Example | Description |
---|---|---|---|---|---|---|
serviceId | URL | ![]() | ID of the service. | |||
requestedfor | query | string | (current user) | "Mary" | User ID to request on behalf of someone else. If this parameter is not presented, the request is for the current user. |
Response
Response | Value | Notes |
---|---|---|
HTTP code | 200 | Successful response returns array of questions. Note: Structure of questionnaire may vary between services. Refer to documentation of questionnaire. |
type | application/json | Not applicable. |
{
"requestId": "1111",
"externalId": 2222,
"questionnaire": {
"id": "1",
"pages": [
{
"id": "0",
"title": "Default Page",
"pageItems": [
{
"type": "Dropdown",
"id": "0",
"visible": true,
"label": "machine name",
"description": "",
"required": true,
"defaultAnswer": null,
"options": [
{
"dataValue": "SCCM-2012",
"displayValue": "SCCM-2012"
},
{
"dataValue": "WIN-7X64",
"displayValue": "WIN-7X64"
}
]
},
{
"type": "TextField",
"id": "1",
"visible": true,
"label": "question answers",
"description": "",
"required": true,
"defaultAnswer": "null",
"maxLength": 254
},
{
"type": "TextField",
"id": "2",
"visible": true,
"label": "user name",
"description": "",
"required": true,
"defaultAnswer": "null",
"maxLength": 254
}
]
}
]
}
}
Error handling
Failed requests return an error object with the following properties.
Argument | Type | Description |
---|---|---|
message | string | Error message with error code. |
To send an answer to a question
Respond to a question ID from the list returned from the request.
Note
Each required question must be answered before the request can be submitted.
Method | Endpoint |
---|---|
POST | /services/{serviceId}/questionnaire/answers |
Parameters
Name | Where | Type | Required | Description |
---|---|---|---|---|
serviceId: the id of the service | url | Yes | The ID of the service. | |
questionnaireId | body | string | No | Not applicable. |
questionId | body | string | No | Not applicable. |
answers | body | string | No | Not applicable. |
serviceRequestId | body | string | No | Not applicable. |
{
"questionnaireId": "000000000000001",
"questionId": "0",
"answers": ["My First Name"],
"serviceRequestId": "000000000000007"
}
Response
Response | Value | Notes |
---|---|---|
HTTP code | 200 | Successful response shows the changes of visibility by ID based on answers submitted. |
type | application/json | Not applicable. |
Returned values indicate how the answer being submitted impacts answers, options and visibilities of other questions by ID.
{
1:[
"answers": ["aa", "bb"],
"options": [ {"dataValue": "1","displayValue": "ONE"},
{"dataValue": "2","displayValue": "TWO"}
],
"visible": true
]
}
Error handling
Failed requests return an error object with the following properties.
Argument | Type | Description |
---|---|---|
message | string | Error message with error code. |
To submit the specified request to the specified service
Method | Endpoint |
---|---|
POST | /services/{serviceId}/requests/{requestId}/submissions |
Parameters
Name | Where | Required | Description |
---|---|---|---|
serviceId | URL | Yes | ID of the service. |
requestId | URL | Yes | ID of the request. |
Response
Response | Value | Notes |
---|---|---|
HTTP code | 200 | Successful returns an empty content body. |
type | application/json | Not applicable. |
Error handling
Failed requests return an error object with the following properties.
Argument | Type | Description |
---|---|---|
message | string | Error message with error code. |
To retrieve all requests of a specific service by the current user
Method | Endpoint |
---|---|
GET | /services/{serviceId}/myrequests |
Parameters
Name | Where | Type | Required | Default | Example | Description |
---|---|---|---|---|---|---|
serviceId | URL | Yes | ID of the service. | |||
perPage | query | integer | No | 10 | 20 | Page size. |
page | query | integer | No | 1 | 1 | Page number. |
Response
Response | Value |
---|---|
HTTP code | 200 |
type | application/json |
{
"totalSize": 2,
"data": [
{
"id": "1204",
"serviceId": "000000000000511",
"status": "COMPLETED",
"startTime": "2015-08-24T20:58:06.581+0000",
"lastModifiedTime": "2015-08-24T20:58:06.606+0000",
"completeTime": "2015-08-24T20:58:06.606+0000"
},
{
"id": "1205",
"serviceId": "000000000000511",
"status": "COMPLETED",
"startTime": "2015-08-24T21:06:00.244+0000",
"lastModifiedTime": "2015-08-24T21:06:00.245+0000",
"completeTime": "2015-08-24T21:06:00.245+0000"
}
]
}
Error handling
Failed requests return an error object with the following properties.
Argument | Type | Description |
---|---|---|
message | string | Error message with error code. |
To find requests
This call endpoint can be used to display a list of service requests on the user's request timeline. If a user is not specified, all requests are displayed.
Method | Endpoint |
---|---|
GET | /services/requests |
Parameters
Name | Where | Type | Example | Description |
---|---|---|---|---|
requestedfor | query | string | "Mary" | Filter requests that are requested for the specified user. |
requestedby | query | string | "Francie" | Filter requests that are requested by the specified user. |
since | query | date | Tue, 08 Mar 2016 17:49:05 GMT | Filter requests that are updated since the specified timestamp. |
max | query | integer | 30 | Maximum amount of requests that will be retrieved. |
Response
Response | Value | Notes |
---|---|---|
HTTP code | 200 | Successful response returns a requests object array. |
type | application/json | Not applicable. |
[
{
"id": "4402",
"requestingUserId": "Allen",
"requestForUserId": "Allen",
"name": "New environment test",
"description": "<p>test</p>",
"excerpt": "test",
"price": {
"paymentType": "Free",
"currency": "USD"
},
"status": {
"id": "4402",
"serviceId": "000000000004201",
"status": "ACTIVE",
"startTime": "2016-03-08T20:32:12.000+0000",
"lastModifiedTime": "2016-03-08T20:32:12.000+0000"
},
"quantity": 1,
"logoUrl": "/mp/media/.../file.png?sha=c9eb1a96d6eea52f",
"onceCost": 0,
"monthlyCost": 0,
"yearlyCost": 0
},
{
"id": "4302",
"requestingUserId": "Allen",
"requestForUserId": "Allen",
"name": "New environment test",
"description": "<p>test</p>",
"excerpt": "test",
"price": {
"paymentType": "Free",
"currency": "USD"
},
"status": {
"id": "4302",
"serviceId": "000000000004201",
"status": "FAILED",
"startTime": "2016-03-08T19:21:27.000+0000",
"lastModifiedTime": "2016-03-08T19:21:27.000+0000"
},
"quantity": 1,
"logoUrl": "/mp/media/.../file.png?sha=c9eb1a96d6eea52f",
"onceCost": 0,
"monthlyCost": 0,
"yearlyCost": 0
},
{
"id": "4301",
"requestingUserId": "Allen",
"requestForUserId": "Allen",
"name": "SJ Bundle 1",
"description": "<p>fhyfgjhgjghghghjgh<br/></p>",
"excerpt": "yhytrtrtytryghhghhfhfh",
"price": {
"paymentType": "Once",
"currency": "USD",
"paymentSchedule": ""
},
"status": {
"id": "4301",
"serviceId": "000000000001716",
"status": "COMPLETED",
"startTime": "2016-03-08T19:12:08.000+0000",
"lastModifiedTime": "2016-03-08T19:12:08.000+0000"
},
"provisioningTime": {
"type": "ProvisioningTimeMetric",
"value": 10,
"timeUnit": "DAY"
},
"quantity": 1,
"logoUrl": "/mp/media/.../file.png?sha=3e8a0899fe7e867f",
"onceCost": 200,
"monthlyCost": 200,
"yearlyCost": 2400
}
]
Error handling
Failed requests return an error object with the following properties.
Argument | Type | Description |
---|---|---|
message | string | Error message with error code. |
To find requests by IDs
Method | Endpoint |
---|---|
POST | /services/requests/search |
Parameters
Name | Where | Type | Required | Example | Description |
---|---|---|---|---|---|
body | string | ![]() | ["4402", "4302", "4301"] | Service request ID numbers represented as a list of string values. |
["4402", "4302", "4301"]
Response
Response | Value | Notes |
---|---|---|
HTTP code | 200 | Successful response returns array of service request objects. |
type | application/json | Not applicable. |
[
{
"id": "4402",
"requestingUserId": "Allen",
"requestForUserId": "Allen",
"name": "New environment test",
"description": "<p>test</p>",
"excerpt": "test",
"price": {
"paymentType": "Free",
"currency": "USD"
},
"status": {
"id": "4402",
"serviceId": "000000000004201",
"status": "ACTIVE",
"startTime": "2016-03-08T20:32:12.000+0000",
"lastModifiedTime": "2016-03-08T20:32:12.000+0000"
},
"quantity": 1,
"logoUrl": "/mp/media/.../file.png?sha=c9eb1a96d6eea52f",
"onceCost": 0,
"monthlyCost": 0,
"yearlyCost": 0
},
{
"id": "4302",
"requestingUserId": "Allen",
"requestForUserId": "Allen",
"name": "New environment test",
"description": "<p>test</p>",
"excerpt": "test",
"price": {
"paymentType": "Free",
"currency": "USD"
},
"status": {
"id": "4302",
"serviceId": "000000000004201",
"status": "FAILED",
"startTime": "2016-03-08T19:21:27.000+0000",
"lastModifiedTime": "2016-03-08T19:21:27.000+0000"
},
"quantity": 1,
"logoUrl": "/mp/media/.../file.png?sha=c9eb1a96d6eea52f",
"onceCost": 0,
"monthlyCost": 0,
"yearlyCost": 0
},
{
"id": "4301",
"requestingUserId": "Allen",
"requestForUserId": "Allen",
"name": "SJ Bundle 1",
"description": "<p>fhyfgjhgjghghghjgh<br/></p>",
"excerpt": "yhytrtrtytryghhghhfhfh",
"price": {
"paymentType": "Once",
"currency": "USD",
"paymentSchedule": ""
},
"status": {
"id": "4301",
"serviceId": "000000000001716",
"status": "COMPLETED",
"startTime": "2016-03-08T19:12:08.000+0000",
"lastModifiedTime": "2016-03-08T19:12:08.000+0000"
},
"provisioningTime": {
"type": "ProvisioningTimeMetric",
"value": 10,
"timeUnit": "DAY"
},
"quantity": 1,
"logoUrl": "/mp/media/.../file.png?sha=3e8a0899fe7e867f",
"onceCost": 200,
"monthlyCost": 200,
"yearlyCost": 2400
}
]
Error handling
Failed requests return an error object with the following properties.
Argument | Type | Description |
---|---|---|
message | string | Error message with error code. |
To find a request by its ID
Method | Endpoint |
---|---|
GET | /services/requests/{requestId} |
Parameters
Name | Where | Required | Example | Description |
---|---|---|---|---|
requestId | URL | ![]() | "4402" | ID of the request. |
Response
Response | Value | Notes |
---|---|---|
HTTP code | 200 | Successful response returns a service request object. |
type | application/json | Not applicable. |
{
"id": "4402",
"requestingUserId": "Allen",
"requestForUserId": "Allen",
"name": "New environment test",
"description": "<p>test</p>",
"excerpt": "test",
"price": {
"paymentType": "Free",
"currency": "USD"
},
"status": {
"id": "4402",
"serviceId": "000000000004201",
"status": "ACTIVE",
"startTime": "2016-03-08T20:32:12.000+0000",
"lastModifiedTime": "2016-03-08T20:32:12.000+0000"
},
"quantity": 1,
"logoUrl": "/mp/media/.../file.png?sha=c9eb1a96d6eea52f",
"onceCost": 0,
"monthlyCost": 0,
"yearlyCost": 0
}
Error handling
Failed requests return an error object with the following properties.
Argument | Type | Description |
---|---|---|
message | string | Error message with error code. |
To find all answers submitted for the given request
Method | Endpoint |
---|---|
GET | /services/requests/{requestId}/answers |
Parameters
Name | Where | Required | Description |
---|---|---|---|
requestId | URL | ![]() | ID of the request. |
Response
Response | Value | Notes |
---|---|---|
HTTP code | 200 | Successful response returns a question object with completed answers. |
type | application/json | Not applicable. |
[
{
"questionnaireId": "1",
"questionId": "0",
"questionType": "TextField",
"label": "text field 1",
"options": [
{
"dataValue": "text 1",
"displayValue": "text 1"
}
],
"answers": [
"text 1"
]
},
{
"questionnaireId": "1",
"questionId": "1",
"questionType": "TextField",
"label": "text field 2",
"options": [
{
"dataValue": "text 2",
"displayValue": "text 2"
}
],
"answers": [
"text 2"
]
}
]
Error handling
Failed requests return an error object with the following properties.
Argument | Type | Description |
---|---|---|
message | string | Error message with error code. |
Reviews
To retrieve all reviews
Method | Endpoint |
---|---|
GET | /reviews |
Parameters
Name | Where | Type | Required | Default | Example | Description |
---|---|---|---|---|---|---|
serviceId | query | string | No | 123 | Retrieves reviews of a given service. | |
userId | query | string | No | hannah | Retrieves reviews of a given user. The platform variable $USER$ can be sent as the userId of the current user. | |
perPage | query | integer | No | -1 | 20 | Page size. -1 for non-paginated search. |
page | query | integer | No | 1 | 1 | Page number |
sortBy | query | string | No | modifiedDate | Sorting criteria. Currently only "modifiedDate" | |
sortDirection | query | string | No | asc | asc | Sorting direction: either ascending or descending. |
requestedfor | query | String | No | Mary | When a specific user is specified, the entitlement check is performed against the user. Otherwise, entitlement is checked on the current user. |
Response
Response | Value | Notes |
---|---|---|
HTTP code | 200 | Successful response returns array of reviews objects. |
type | application/json | Not applicable. |
{
"reviews": [
{
"id": "1",
"serviceId": "123",
"userId": "2345",
"title": "review title1",
"content": "review content1",
"modifiedDate": "2015-08-20T00:24:22.000+0000"
},
{
"id": "2",
"serviceId": "124",
"userId": "2346",
"title": "review title2",
"content": "review content2",
"modifiedDate": "2015-08-21T00:24:22.000+0000"
}
],
"pageSize": 10,
"page": 1,
"total": 2
}
Error handling
Failed requests return an error object with the following properties.
Argument | Type | Description |
---|---|---|
message | string | Error message with error code. |
To create a review for a given service
Method | Endpoint |
---|---|
POST | /reviews |
Parameters
Name | Where | Type | Required | Example | Description |
---|---|---|---|---|---|
serviceId | body | string | ![]() | "123" | ID of the service. |
title | body | string | ![]() | "review title1" | Title of the review. |
content | body | string | ![]() | "review content1" | Content of the review. |
{
"serviceId": "123",
"title": "review title1",
"content": "review content1"
}
Response
Response | Value | Notes |
---|---|---|
HTTP code | 201 | Successful response returns no content. |
Error handling
Failed requests return an error object with the following properties.
Argument | Type | Description |
---|---|---|
HTTP code | 422 | Service ID is not found. |
message | string | Error message with error code. |
data | string | Error message description. |
{
"message": "Service of id {id} not found."
}
To retrieve a review by its ID
Method | Endpoint |
---|---|
GET | /reviews/{reviewId} |
Parameters
Name | Where | Required | Example | Description |
---|---|---|---|---|
reviewId | URL | Yes | ID of the review. | |
requestedfor | query | No | Mary | When a user is specified, the entitlement check is performed against the user. Otherwise, entitlement is checked on the current user. |
Response
Response | Value | Notes |
---|---|---|
HTTP code | 200 | Successful response returns a review object. |
type | application/json | Not applicable. |
{
"id": "1",
"serviceId": "123",
"userId": "2345",
"title": "review title1",
"content": "review content1",
"modifiedDate": "2015-08-20T00:24:22.000+0000"
}
Error handling
Failed requests return an error object with the following properties.
Argument | Type | Description |
---|---|---|
HTTP code | 404 | Review with requested ID not found. |
message | string | Error message with error code. |
data | string | Error message description. |
{
"message": "ERROR (302): Entry does not exist in database"
}
To update a review
Reviews can be updated only if the review was originally entered under the current user's account. Admin users cannot update reviews submitted by other users.
Method | Endpoint |
---|---|
PUT | /reviews/{reviewId} |
Parameters
Name | Where | Type | Required | Default | Example | Description |
---|---|---|---|---|---|---|
reviewId | URL | Yes | ID of the review to be updated. | |||
title | body | string | No | "new title" | Updated title. If title and content are both empty, change will be ignored. | |
content | body | string | No | "new content" | Updated content. If title and content are both empty, the change will be ignored. |
{
"title": "new title",
"content": "new content"
}
Response
Response | Value | Notes |
---|---|---|
HTTP code | 200 | Successful response returns no content. |
Error handling
Failed requests return an error object with the following properties.
Argument | Type | Description |
---|---|---|
message | string | Error message with error code. |
To delete a review
Reviews can be deleted only if the review was originally entered under the current user's account. Admin users cannot delete reviews submitted by other users.
Method | Endpoint |
---|---|
DELETE | /reviews/{reviewId} |
Parameters
Name | Where | Type | Required | Description |
---|---|---|---|---|
reviewId | URL | ![]() | ID of the review to be deleted. |
Response
Response | Value | Notes |
---|---|---|
HTTP code | 200 | Successful response returns no content. |
Error handling
Failed requests return an error object with the following properties.
Argument | Type | Description |
---|---|---|
message | string | Error message with error code. |
Ratings
Rating is given as percentage (between 0 and 1)
To retrieves all ratings
Method | Endpoint |
---|---|
GET | /ratings |
Parameters
Param Name | Where | Type | Required | Default | Example | Description |
---|---|---|---|---|---|---|
serviceId | body | string | No | 123 | Retrieves ratings of a given service. | |
userId | body | string | No | 20 | Retrieves ratings from a given user. $USER$ can be used for current user. | |
perPage | body | integer | No | -1 | 20 | Page size. -1 for non-paginated search. |
page | body | integer | No | -1 | 1 | Page number. |
requestedfor | query | String | No | When a user is specified, the entitlement check is performed against the user. Otherwise, entitlement is checked on the current user. |
Response
Response | Value | Notes |
---|---|---|
HTTP code | 200 | Successful response returns an array of ratings objects. |
type | application/json | Not applicable. |
{
"ratings": [
{
"id": "1",
"serviceId": "123",
"userId": "2345",
"rating": 0.8,
"modifiedDate": "2015-08-20T00:24:22.000+0000"
},
{
"id": "2",
"serviceId": "124"
"userId": "2345",
"rating": 0.7,
"modifiedDate": "2015-08-20T00:24:22.000+0000"
}
],
"pageSize": 10,
"page": 1,
"total": 2
}
Error handling
Failed requests return an error object with the following properties.
Argument | Type | Description |
---|---|---|
message | string | Error message with error code. |
To create a rating for a service
Method | Endpoint |
---|---|
POST | /ratings |
Parameters
Name | Where | Type | Required | Example | Description |
---|---|---|---|---|---|
serviceId | body | string | Yes | "123" | ID of the service to be rated. |
rating | body | float | Yes | 0.8 | Rating value submitted as a percentage (number between 0 and 1). |
{
"serviceId": "123",
"rating": 0.8
}
Response
Response | Value | Notes |
---|---|---|
HTTP code | 201 | Successful response returns no content. |
Error handling
Failed requests return an error object with the following properties.
Argument | Type | Description |
---|---|---|
message | string | Error message with error code. |
To retrieve a rating by its ID
Method | Endpoint |
---|---|
GET | /ratings/{ratingId} |
Parameters
Name | Where | Type | Example | Description |
---|---|---|---|---|
ratingId | URL | ID of the rating to retrieve. | ||
requestedfor | query | String | Mary | When a user is specified, the entitlement check is performed against the user. Otherwise, entitlement is checked on the current user. |
Response
Response | Value | Notes |
---|---|---|
HTTP code | 200 | Successful response returns a rating object. |
type | application/json | Not applicable. |
{
"id": "1",
"serviceId": "123",
"userId": "2345",
"rating": 0.8
}
Error handling
Failed requests return an error object with the following properties.
Argument | Type | Description |
---|---|---|
message | string | Error message with error code. |
To update a rating
Ratings can be updated only if the rating was originally entered under the current user's account. Admin users cannot update ratings submitted by other users.
Method | Endpoint |
---|---|
PUT | /ratings/{ratingId} |
Parameters
Name | Where | Type | Required | Example | Description |
---|---|---|---|---|---|
ratingId | URL | Yes | 4321 | The ID of the rating to update | |
rating | body | float | Yes | 0.6 | The rating value submitted as a percentage (number between 0 and 1). |
{
"rating": 0.6
}
Response
Response | Value | Notes |
---|---|---|
HTTP code | 200 | Successful response returns no content. |
Error handling
Failed requests return an error object with the following properties.
Argument | Type | Description |
---|---|---|
message | string | Error message with error code. |
Service migration
To export selected services
This endpoint packages service data and media files into a binary zip archive. Includes full catalog profiles, images, workflows, and questions
Method | Endpoint |
---|---|
POST | /services/export |
Parameters
Name | Where | Type | Required | Example | Description |
---|---|---|---|---|---|
(array list) | body | string | Yes | ["000000000012912", "000000000012913"] | List of service ids that are to be exported. |
[
"000000000012912", "000000000012913", ...
]
Response
A zip file containing the exported services.
To import a service zip file
Extracts an uploaded binary zip file and creates services with full catalog profiles, images, workflows, and questions.
Method | Endpoint |
---|---|
POST | /services/import |
Parameters
Name | Where | Type | Required | Description |
---|---|---|---|---|
(uploaded file) | body | binary data (zip file) | Yes | Upload requires the following form setting:
|
Response
Response | Value | Notes |
---|---|---|
HTTP code | 200 | When import is successful. |
Comments