Global App Configuration Service
Troubleshooting the Global Apps Configuration Service APIs
This document describes the error codes and responses that Global Apps Configuration Service APIs return. The response codes for the following APIs are covered in this document:
An unsuccessful Global App Configuration service API request returns the following error information in the response body:
- type - A standard HTTP response code. For example,
HTTP Status Code 404: Entity not found. - details - A brief description of the error.
- parameters - An optional JSON object to provide additional information about the error.
Following is a sample API error response code:
{
"type": "HTTP Status Code 404: Entity not found",
"detail": "resource not found",
"parameters": {
"name": "entityType",
"value": "the request URL"
}
}
<!--NeedCopy-->
Discovery APIs
| APIs | Description |
|---|---|
| GET /discovery | The GET request is called to fetch the result of all the discovery records for a specific customer. After the customer creates a discovery record based on the app (Product) and domain, the result is displayed. The GET request also helps in determining if the customer has claimed and created a discovery record based on a domain. This request returns an HTTP 200 response with a collection of discovery records for the requested customer. |
| POST /discovery/app/{app}/domain | The POST request is placed only once for a combination of app and domain. In case the request is already placed the error is as per HTTP 409 response code. The body parameters for both PUT and POST are the same and are explained in the following sections. |
| GET /discovery/app/{app}/domain/{domain} | The GET operation for a particular discovery record is based on the app and domain name. This request returns an HTTP 200 response with a single discovery record in a collection. |
| PUT /discovery/app/{app}/domain/{domain} | The PUT request is used to update a discovery record with the combination of app and domain. The body parameters for both PUT and POST are the same and are explained in the following sections. This request returns an HTTP 204 No Content response on a successful update. |
| DELETE /discovery/app/{app}/domain/{domain} | The DELETE request is used to delete a discovery record with the combination of app and domain. This request returns an HTTP 204 No Content response on a successful delete. |
Sample Request
{
"domain": {
"name": "aca.example.com"
},
"app": {
"workspace": {
"serviceURLs": [
{
"url": "https://nsg.example.com:443"
},
{
"url": "https://store.example.com:443/Citrix/Store"
}
]
}
}
}
<!--NeedCopy-->
POST and PUT body parameters
| Parameters | Description |
|---|---|
| domain | The values are case sensitive. |
| app | enum value allowed is “workspace”. The values are case sensitive. |
| serviceURLs | enum value allowed is “url”. The values are case sensitive. |
| url | The values are case sensitive. The values require the protocol “https” or “HTTP” and port number. |
POST, PUT, GET, and DELETE path parameters
| Parameters | Description |
|---|---|
| app | enum values allowed “workspace”. The values aren’t case sensitive. |
| domain PUT GET DELETE only | The values are case sensitive. |
Response codes for Discovery APIs
The following table lists the response codes and their description for the Discovery APIs.
| HTTP status code | API | Description |
|---|---|---|
| 200 OK | ||
| GET /discovery | The status code indicates that the request has succeeded. For more information, see use cases. | |
| 201 Created | ||
| POST /discovery/app/{app}/domain | The status code indicates that the request has been fulfilled and has resulted in one or more new resources being created. For more information, see use cases. | |
| 204 No Content | ||
| PUT /discovery/app/{app}/domain{domain} | Records are updated or deleted successfully. The status code indicates that the server has successfully fulfilled the request and there’s no additional content to send in the response body. | |
| 400 Validation Errors | ||
| POST /discovery/app/{app}/domain | The status code indicates that the server cannot process the request because of a perceived client error. For more information, see use cases. | |
| PUT /discovery/app/{app}/domain/{domain} | ||
| 401 Unauthorized | ||
| GET /discovery | The status code indicates that the request isn’t applied because it lacks valid authentication credentials for the target resource. For more information, see use cases. | |
| POST /discovery/app/{app}/domain/ | ||
| GET /discovery/app/{app}/domain/{domain} | ||
| PUT /discovery/app/{app}/domain/{domain} | ||
| DELETE /discovery/app/{app}/domain/{domain} | ||
| 403 Forbidden | ||
| GET /discovery | The status code indicates that the server understood the request but refuses to authorize the request. For more information, see use cases. | |
| POST /discovery/app/{app}/domain/ | ||
| GET /discovery/app/{app}/domain/{domain} | ||
| PUT /discovery/app/{app}/domain/{domain} | ||
| DELETE /discovery/app/{app}/domain/{domain} | ||
| 404 Not Found | ||
| GET /discovery | The status code indicates that the origin server didn’t find a current representation for the target resource or isn’t willing to reveal that one that exists. For more information, see use cases. | |
| GET /discovery/app/{app}/domain/{domain} | ||
| PUT /discovery/app/{app}/domain/{domain} | ||
| DELETE /discovery/app/{app}/domain/{domain} | ||
| 409 Conflict | ||
| POST /discovery/app/{app}/domain/ | The status code indicates that the request can’t complete because of a conflict with the current state of the target resource. For more information, see use cases. | |
| 503 Service Unavailable | ||
| GET /discovery | The status code indicates that the server is unable to handle the request because of a temporary overload or scheduled maintenance, and likely to alleviate after some delay. For more information, see use cases. Note: Report these errors directly to the engineering team to help resolve the issues. Take a note of the customer ID and transaction ID from the customer to troubleshoot further. | |
| GET /discovery/app/{app}/domain/{domain} | ||
| POST /discovery/app/{app}/domain/ | ||
| PUT /discovery/app/{app}/domain/{domain} |
HTTP status code: 200 OK
Case 1: When the customers have saved a single record
[
{
"domain": {
"name": "aca.example.com"
},
"app": {
"workspace": {
"serviceURLs": [
{
"url": "https://nsg.example.com:443"
},
{
"url": "https://store.example.com:443/Citrix/Store"
}
]
}
}
}
]
<!--NeedCopy-->
Case 2: When the customers have saved multiple records
[
{
"domain": {
"name": "aca.example.com"
},
"app": {
"workspace": {
"serviceURLs": [
{
"url": "https://nsg.example.com:443"
},
{
"url": "https://store.example.com:443/Citrix/Store"
}
]
}
}
},
{
"domain": {
"name": "aca.example1.com"
},
"app": {
"workspace": {
"serviceURLs": [
{
"url": "https://nsg.example.com:443"
},
{
"url": "https://store.example.com:443/Citrix/Store"
}
]
}
}
}
]
<!--NeedCopy-->
HTTP status code: 201 Created
Case 1: When the request is successful
{
"domain": {
"name": "aca.example1.com"
},
"app": {
"workspace": {
"serviceURLs": [
{
"url": "https://nsg.example.com:443"
},
{
"url": "https://store.example.com:443/Citrix/Store"
}
]
}
}
}
<!--NeedCopy-->
HTTP status code: 400 Validation error
Case 1: If the fields are empty the error shows the mandatory fields to be filled
{
"detail": "App name is null or Invalid",
"type": "HTTP Status Code 400: Bad Request",
"parameters": [
{
"name": "appName",
"value": "{app}"
},
{
"name": "domainName",
"value": "{yourDomainName}"
},
{
"name": "ccCustomerId",
"value": "{yourCustomerId}"
}
]
}
<!--NeedCopy-->
Case 2: When the app or product is invalid
{
"detail": "App name is null or Invalid",
"type": "HTTP Status Code 400: Bad Request",
"parameters": [
{
"name": "app",
"value": "{app}"
},
{
"name": "ccCustomerId",
"value": "{yourCustomerId}"
}
]
}
<!--NeedCopy-->
Case 3: When a domain is invalid
{
"detail": "Discovery handle not verified by Domain Claim",
"type": "HTTP Status Code 400: Bad Request",
"parameters": [
{
"name": "appName",
"value": "workspace"
},
{
"name": "ccCustomerId",
"value": "{yourCustomerId}"
}
]
}
<!--NeedCopy-->
HTTP status code: 401 Unauthorized
Case 1: If the Authorization header is empty or missing, the reason is mentioned in the parameters value as missing
{
"detail": "Unauthorized HTTP request",
"type": "HTTP Status Code 401: Unauthorized",
"parameters": [
{
"name": "Reason",
"value": "Missing"
}
]
}
<!--NeedCopy-->
Case 2: If the Authorization header is invalid, the reason is mentioned in the parameters value as invalid
{
"detail": "Unauthorized HTTP request",
"type": "HTTP Status Code 401: Unauthorized",
"parameters": [
{
"name": "Reason",
"value": "Invalid"
}
]
}
<!--NeedCopy-->
HTTP status code: 403 Forbidden
Case 1: Customer isn’t entitled to use the service
{
"detail": "Access denied",
"type": "HTTP Status Code 403: Forbidden",
"parameters": [
{
"name": "ccCustomerId",
"value": "{yourCustomerId}"
}
]
}
<!--NeedCopy-->
HTTP status code: 404 Not Found
Case 1: The requested record wasn’t found
{
"detail": "Resource not found",
"type": "HTTP Status Code 404: Entity not found",
"parameters": [
{
"name": "app",
"value": "{app}"
},
{
"name": "domain",
"value": "{yourDomain}"
},
{
"name": "ccCustomerId",
"value": "{yourCustomerId}"
}
]
}
<!--NeedCopy-->
HTTP status code: 409 Conflict
{
"detail": "Resource already exist for domain name",
"type": "HTTP Status Code: 409: Conflict",
"parameters": [
{
"name": "ccCustomerId",
"value": "{yourCustomerId}"
}
]
}
<!--NeedCopy-->
HTTP status code: 503 Service Unavailable
Case 1: Internal Server Errors
{
"detail": "Service unavailable",
"type": "HTTP Status Code 503: Service Unavailable",
"parameters": [
{
"name": "ccCustomerId",
"value": "{yourCustomerId}"
},
{
"name": "app",
"value": "{app}"
},
{
"name": "domain",
"value": "{domain}"
}
]
}
<!--NeedCopy-->
Settings APIs
| APIs | Description |
|---|---|
| GET /settings | The GET request is called to fetch the result of all the settings records for a specific customer. After the customer creates a setting record based on the app (Product) and service URL, the result is displayed. The GET request also helps in determining if a domain has been claimed and created a setting record based on a domain. This request returns an HTTP 200 response with a collection of settings records. |
| POST /settings/app/{app}/url | The POST request is placed only once for a combination of app and url. In case the request is already placed and if a record for app and url combination exists the HTTP 409 response code is returned. The body parameters for both PUT and POST are the same and are explained in the following sections. |
| GET /settings/app/{app}/url/{url} | This request returns an HTTP 200 response with a settings record for an app and url. |
| PUT /settings/app/{app}/url/{url} | The PUT request is used to update a settings record for a combination of app and url. The body parameters for both PUT and POST are the same and are explained in the following sections. This request returns an HTTP 204 No Content response on a successful update. |
| DELETE /settings/app/{app}/url/{url} | The DELETE request is used to delete a settings record for a combination of app and url. This request returns an HTTP 204 No Content response on a successful delete. |
Sample request
{
"serviceURL": {
"url": "https://sampleworkspace.cloud.com:443"
},
"settings": {
"name": "Productivity Apps",
"description": "Provides access to MS Office Apps",
"useForAppConfig": true,
"appSettings": {
"ios": [
{
"category": "Audio",
"userOverride": false,
"assignedTo": [
"AllUsersNoAuthentication"
],
"assignmentPriority": 0,
"settings": [
{
"name": "audio",
"value": "true"
}
]
},
{
"category": "Display",
"userOverride": false,
"assignedTo": [
"AllUsersNoAuthentication"
],
"assignmentPriority": 0,
"settings": [
{
"name": "Session Resolution",
"value": "Autofit High Resolution"
}
]
}
],
"android": [
{
"category": "Audio",
"userOverride": true,
"assignedTo": [
"AllUsersNoAuthentication"
],
"assignmentPriority": 0,
"settings": [
{
"name": "Audio Streaming",
"value": "Play and record"
}
]
}
],
"windows": [
{
"category": "Keyboard",
"userOverride": false,
"assignedTo": [
"AllUsersNoAuthentication"
],
"assignmentPriority": 0,
"settings": [
{
"name": "Use Predictive Text",
"value": "false"
}
]
}
]
}
}
}
<!--NeedCopy-->
POST and PUT body parameters
| Parameter | Description |
|---|---|
| serviceURL | The allowed values are URL objects. |
| url | Values are case sensitive. The values require the protocol “https” or “HTTP” and port number. |
| settings | Values are case sensitive. For Settings Object, see settings matrix in the Getting Started page. |
POST, PUT, GET, DELETE path parameters
| Parameter | Description |
|---|---|
| app | Values are NOT case sensitive. Only valid value is “workspace” |
| url PUT GET DELETE | Values are NOT case sensitive. Encode the value using a base 64 URL. |
Response codes for the Settings APIs
The following table displays the response codes and their description for the Settings APIs.
| HTTP status code | API | Description |
|---|---|---|
| 200 OK | ||
| GET /settings | The status code indicates that the request has succeeded. For more information, see use cases. | |
| 201 Created | ||
| POST /settings/app/{app}/url/ | The status code indicates that the request has been fulfilled and has resulted in one or more new resources being created. For more information, see use cases. | |
| 204 No Content | ||
| PUT /settings/app/{app}/url/{url} No Response | Record were updated or deleted successfully. The status code indicates that the server has successfully fulfilled the request and that there is no additional content to send in the response body. | |
| DELETE /settings/app/{app}/url/{url} No Response | ||
| 400 Validation Errors | ||
| POST /settings/app/{app}/url/ | The status code indicates that the server can’t or will not process the request because of perceived client error. For more information, see use cases. | |
| PUT /settings/app/{app}/url/{url} | ||
| 401 Unauthorized | ||
| GET /settings | The status code indicates that the request isn’t applied because it lacks valid authentication credentials for the target resource. For more information, see use cases. | |
| POST /settings/app/{app}/url/ | ||
| GET /settings/app/{app}/url/{url} | ||
| PUT /settings/app/{app}/url/{url} | ||
| DELETE /settings/app/{app}/url/{url} | ||
| 403 Forbidden | ||
| GET /settings | The status code indicates that the server understood the request but refuses to authorize the request. For more information, see use cases. | |
| POST /settings/app/{app}/url/ | ||
| GET /settings/app/{app}/url/{url} | ||
| PUT /settings/app/{app}/url/{url} | ||
| DELETE /settings/app/{app}/url/{url} | ||
| 404 Not Found | ||
| GET /settings | The status code indicates that the origin server didn’t find a current representation for the target resource or isn’t willing to reveal that one exists. For more information, see use cases. | |
| GET /settings/app/{app}/url/{url} | ||
| PUT /settings/app/{app}/url/{url} | ||
| DELETE /settings/app/{app}/url/{url} | ||
| 409 Conflict | ||
| POST /settings/app/{app}/url/ | The status code indicates that the request can’t complete due to a conflict with the current state of the target resource. For more information, see use cases. | |
| 503 Service Unavailable | ||
| GET /settings | The status code indicates that the server is unable to handle the request because of a temporary overload or scheduled maintenance, which will likely alleviate after some delay. For more information, see use cases. Note: Report these errors directly to the engineering team to help resolve the issues. Take a note of the customer ID and Transaction ID from the customer to troubleshoot further. | |
| POST /settings/app/{app}/url/ | ||
| GET /settings/app/{app}/url/{url} | ||
| PUT /settings/app/{app}/url/{url} |
HTTP status code: 200 OK
Case 1: When a single record has been created
{
"serviceURL": {
"url": "https://sampleworkspace.cloud.com:443"
},
"settings": {
"name": "Productivity Apps",
"description": "Provides access to MS Office Apps",
"useForAppConfig": true,
"appSettings": {
"ios": [
....
],
"android": [
....
],
"windows": [
....
]
}
}
}
<!--NeedCopy-->
Case 2: When multiple records are created
[
{
"serviceURL": {
"url": "https://[yourWorkspaceSite]:443"
},
"settings": {
"name": "Productivity Apps",
"description": "Provides access to MS Office Apps",
"useForAppConfig": true,
"appSettings": {
"ios": [
....
],
"android": [
....
],
"windows": [
....
]
}
}
},
{
"serviceURL": {
"url": "https://sampleworkspace.cloud.com:443"
},
"settings": {
"name": "Productivity Apps",
"description": "Provides access to MS Office Apps",
"useForAppConfig": true,
"appSettings": {
"ios": [
....
],
"android": [
....
],
"windows": [
....
]
}
}
}
]
<!--NeedCopy-->
HTTP status code: 201 Created
Case 1: When a request is successful
{
"serviceURL": {
"url": "https://sampleworkspace.cloud.com:443"
},
"settings": {
"name": "Productivity Apps",
"description": "Provides access to MS Office Apps",
"useForAppConfig": true,
"appSettings": {
"ios": [
....
],
"android": [
....
],
"windows": [
....
]
}
}
}
<!--NeedCopy-->
HTTP status code: 400 Validation Errors
Case 1: If the fields are empty the error shows the mandatory fields to be filled
{
"detail": "App name is null or Invalid",
"type": "HTTP Status Code 400: Bad Request",
"parameters": [
{
"name": "app",
"value": "{app}"
},
...
{
"name": "url",
"value": "{url}"
},
...
{
"name": "ccCustomerId",
"value": "{yourCustomerId}"
}
]
}
<!--NeedCopy-->
Case 2: When the app or product is invalid
{
"detail": "App name is null or Invalid",
"type": "HTTP Status Code 400: Bad Request",
"parameters": [
{
"name": "app",
"value": "{app}"
},
{
"name": "ccCustomerId",
"value": "{yourCustomerId}"
}
]
}
<!--NeedCopy-->
Case 3: When service URL is invalid
{
"detail": "Input byte array has wrong x-byte ending unit",
"type": "HTTP Status Code 400: Bad Request",
"parameters": [
{
"name": "url",
"value": "{url}"
},
{
"name": "ccCustomerId",
"value": "{yourCustomerId}"
}
]
}
<!--NeedCopy-->
Case 4: When service URL isn’t base 64 URL encoded
{
"detail": "Illegal base64 character 2e",
"type": "HTTP Status Code 400: Bad Request",
"parameters": [
{
"name": "url",
"value": "{url}"
},
{
"name": "ccCustomerId",
"value": "{yourCustomerId}"
}
]
}
<!--NeedCopy-->
HTTP status code: 401 Unauthorized
Case 1: If the Authorization header is empty or the parameter value is missing
{
"detail": "Unauthorized HTTP request",
"type": "HTTP Status Code 401: Unauthorized",
"parameters": [
{
"name": "Reason",
"value": "Missing"
}
]
}
<!--NeedCopy-->
Case 2: If the Authorization header is invalid, the parameters value is invalid
{
"detail": "Unauthorized HTTP request",
"type": "HTTP Status Code 401: Unauthorized",
"parameters": [
{
"name": "Reason",
"value": "Invalid"
}
]
}
<!--NeedCopy-->
HTTP status code: 403 Forbidden
Case 1: The customer isn’t entitled to use the service
{
"detail": "Access denied",
"type": "HTTP Status Code 403: Forbidden",
"parameters": [
{
"name": "ccCustomerId",
"value": "{yourCustomerId}"
}
]
}
<!--NeedCopy-->
HTTP status code: 404 Not Found
Case 1: The requested record wasn’t found
{
"detail": "Resource not found",
"type": "HTTP Status Code 404: Entity not found",
"parameters": [
{
"name": "app",
"value": "{app}"
},
{
"name": "url",
"value": "{url}"
},
{
"name": "ccCustomerId",
"value": "{yourCustomerId}"
}
]
}
<!--NeedCopy-->
HTTP status code: 409 Conflict
{
"detail": "Resource already exist for service url",
"type": "HTTP Status Code: 409: Conflict",
"parameters": [
{
"name": "ccCustomerId",
"value": "{yourCustomerId}"
}
]
}
<!--NeedCopy-->
HTTP status code: 503 Service Unavailable
Case 1: Internal Server Errors
{
"detail": "Service unavailable",
"type": "HTTP Status Code 503: Service Unavailable",
"parameters": [
{
"name": "ccCustomerId",
"value": "{yourCustomerId}"
},
{
"name": "app",
"value": "{app}"
},
{
"name": "url",
"value": "{url}"
}
]
}
<!--NeedCopy-->
Troubleshooting the Global Apps Configuration Service APIs
Copied!
Failed!