This documentation supports the 18.02 version of BMC Digital Workplace. To view the latest version, select the version from the Product version menu.

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

MethodEndpoint
POST/users/login

Parameters

NameWhereTypeRequiredDefaultExampleDescription
idbodystring(tick)none<your_user>Digital Workplace Catalog user login account (with organization domain).
passwordbodystring(tick)none<your_password>Password

Example request body

{
	"id": "<your_user>",
	"password": "<your_password>"
}

Response

ResponseValueNotes
HTTP code200Application 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.

NameTypeDescription
messagestringError message with error code.
datastringError message description.

Categories

To retrieve a full category list

MethodURL
GET/categories

Parameters

NameWhereTypeRequiredDefaultExampleDescription
perPagequeryintegerNo-120Page size. -1 for non-paginated search.
pagequeryintegerNo11

Page number

Response

ResponseValueNotes
HTTP code200Returns a category list object array.
typeapplication/jsonNot applicable.
type: application/json

Response properties

NameTypeDescription
pageSizeintegerPass through request parameter.
pageintegerPass through request parameter.
categoriesarrayCategory object array.

Error handling

Failed requests return an error object with the following properties.

ArgumentTypeDescription
messagestringError 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
categoryIdURL YesNone000000000000001Category ID to retrieve.
depthqueryintNo12

Depth of the category being retrieved. Allowed values: 1, 2, 3.

requestedforqueryStringNoNoneMaryWhen 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 code200Returns a category array object. If the requested categoryId does not exist, or does not contain descendants, then an empty array is returned.
typeapplication/jsonNot applicable.


type: application/json

Response properties

NameTypeDescription
idstringCategory ID used by the application.
guidstring

Unique ID used by the platform.

namestringCategory name.
categoryGroupIdstring

Group to which the category belongs.

Currently there is only one category group, referenced as "Type of service".

parentIdstringID of child's parent category(?) or, if no child, null.
childCountintegerNumber of direct descendant categories.
subCategoriesstringNull

Error handling

Failed requests return an error object with the following properties.

Argument
Type
Description
messagestringError message with the error code.

To retrieve category groups

Method
Endpoint

GET

/categories/groups

Parameters

None

Response

Response

Value
Notes
HTTP code200Successfulful returns category array.
typeapplication/jsonNot applicable.
type: application/json

Response properties

Name
Type
idstring
guidstring
namestring
descriptionstring
systemIdstring
groupStatusstring
childCountinteger
categoriesstring

Error handling

Failed requests return an error object with the following properties.

Argument
Type
Description
messagestringError 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

categoryGroupIdURL Yes  Not applicable.
depthbodyintegerNo12Depth of the cateogory being retrieved. Allowed values: 1,2,3
requestedforqueryStringNo MaryWhen 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.
type: application/json


Error handling

Failed requests return an error object with the following properties:

Argument
Type
Description
messagestringError 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

serviceIdURL Yes Not applicable.
requestedforquery parameterStringNoMaryWhen 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

type: application/json

Error handling

Failed requests return an error object with the following properties.

Argument
Type
Description
messagestringError 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.

type: application/json

Method

Endpoint
POST/services/search

Parameters

Name

Where

Type

Required

Default

Example

Description

perPagequeryintegerNo-120Page size. -1 for non-paginated search.
pagequeryintegerNo11

Page number to display.

serviceIdsbodystringNo  Not applicable.
categoryIdbodystringNo  Not applicable.
titlebodystringNo  Not applicable.
requestedforqueryStringNo MaryWhen a user is specified, the entitlement check is performed against the user. Otherwise, entitlement is checked on the current user.
type: application/json

Response

Response

Value

Notes

HTTP code

200

Successful response receives an array of service objects.

type

application/json

 
type: application/json

Error handling

Failed requests return an error object with the following properties:

Argument
Type
Description
messagestringError 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.
type: application/json

Error handling

Failed requests return an error object with the following properties.

Argument
Type
Description
messagestringError 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

serviceIdURL (tick)  ID of the service.
requestedforquerystring (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.
type: application/json

Error handling

Failed requests return an error object with the following properties.

Argument
Type
Description
messagestringError 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 serviceurl YesThe ID of the service.
questionnaireIdbodystringNoNot applicable.
questionIdbodystringNoNot applicable.
answersbodystringNoNot applicable.
serviceRequestIdbodystringNoNot applicable.
type: application/json

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.

type: application/json

Error handling

Failed requests return an error object with the following properties.

Argument
Type
Description
messagestringError 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.

requestIdURL 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
messagestringError 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

serviceIdURL Yes  ID of the service.
perPagequeryintegerNo1020

Page size.

pagequeryintegerNo11Page number.

Response

Response

Value

HTTP code

200

type

application/json

type: application/json

Error handling

Failed requests return an error object with the following properties.

Argument
Type
Description
messagestringError 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.

sincequerydate

Tue, 08 Mar 2016 17:49:05 GMT

Filter requests that are updated since the specified timestamp.
maxqueryinteger30Maximum 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.
type: application/json

Error handling

Failed requests return an error object with the following properties.

Argument
Type
Description
messagestringError message with error code.

To find requests by IDs

Method

Endpoint
POST/services/requests/search

Parameters

Name

Where

Type

Required

Example

Description

 bodystring(tick)
["4402", "4302", "4301"]
Service request ID numbers represented as a list of string values.
type: application/json

Response

Response

Value

Notes

HTTP code

200

Successful response returns array of service request objects.

type

application/json

Not applicable.
type: application/json


Error handling

Failed requests return an error object with the following properties.

Argument
Type
Description
messagestringError message with error code.

To find a request by its ID

Method

Endpoint
GET/services/requests/{requestId}

Parameters

Name

Where

Required

Example

Description

requestIdURL(tick)"4402"ID of the request.

Response

Response

Value

Notes

HTTP code

200

Successful response returns a service request object.

type

application/json

Not applicable.
type: application/json

Error handling

Failed requests return an error object with the following properties.

Argument
Type
Description
messagestringError 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

requestIdURL(tick)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.
type: application/json

Error handling

Failed requests return an error object with the following properties.

Argument
Type
Description
messagestringError 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.

userIdquerystringNo hannahRetrieves 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.

requestedforqueryStringNo MaryWhen 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.
type: application/json


Error handling

Failed requests return an error object with the following properties.

Argument
Type
Description
messagestringError message with error code.

To create a review for a given service

Method

Endpoint
POST/reviews 

Parameters

Name

Where

Type

Required

Example

Description

serviceIdbodystring(tick)"123"ID of the service.
 titlebodystring (tick) "review title1"

Title of the review.

contentbodystring(tick)"review content1"Content of the review.
type: application/json

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.
messagestringError message with error code.
datastring

Error message description.

type: application/json

To retrieve a review by its ID

Method

Endpoint
GET/reviews/{reviewId}

Parameters

Name

Where

Required

Example

Description

reviewIdURLYes ID of the review.
requestedforqueryNoMaryWhen 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.
type: application/json


Error handling

Failed requests return an error object with the following properties.

Argument
Type
Description
HTTP code404Review with requested ID not found.
messagestringError message with error code.
datastring

Error message description.

type: application/json

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

reviewIdURL Yes  ID of the review to be updated.
titlebodystringNo "new title"

Updated title. If title and content are both empty, change will be ignored.

contentbodystringNo "new content"Updated content. If title and content are both empty, the change will be ignored.
type: application/json

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
messagestringError 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

reviewIdURL (tick)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
messagestringError 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

RequiredDefault

Example

Description

serviceId

bodystringNo 

123

Retrieves ratings of a given service.

userId

bodystringNo 

20

Retrieves ratings from a given user. $USER$ can be used for current user.

perPage

bodyintegerNo-1

20

Page size. -1 for non-paginated search.

page

bodyintegerNo-1

1

Page number.

requestedforqueryStringNo  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.
type: application/json


Error handling

Failed requests return an error object with the following properties.

Argument
Type
Description
messagestringError message with error code.

To create a rating for a service

Method

Endpoint
POST/ratings

Parameters

Name

Where

Type

Required

Example

Description

serviceIdbodystringYes"123"ID of the service to be rated.
ratingbodyfloatYes0.8Rating value submitted as a percentage (number between 0 and 1).
type: application/json

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
messagestringError message with error code.

To retrieve a rating by its ID

Method

Endpoint
GET/ratings/{ratingId}

Parameters

Name

Where

Type

Example

Description

ratingIdURL  ID of the rating to retrieve.
requestedforqueryStringMaryWhen 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.
type: application/json


Error handling

Failed requests return an error object with the following properties.

Argument
Type
Description
messagestringError 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

ratingIdURL Yes4321The ID of the rating to update
ratingbodyfloatYes0.6

The rating value submitted as a percentage (number between 0 and 1).

type: application/json

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
messagestringError 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

NameWhereTypeRequiredExampleDescription
(array list)bodystring Yes["000000000012912", "000000000012913"]List of service ids that are to be exported.
type: application/json

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

NameWhereTypeRequiredDescription
(uploaded file)bodybinary data (zip file)Yes

Upload requires the following form setting:

Content-Disposition: form-data; name="file"; filename="{file name}" Content-Type: application/x-zip-compressed

Response

Response

Value

Notes

HTTP code

200

When import is successful.


Was this page helpful? Yes No Submitting... Thank you

Comments