DevOps Config API

  • Release version: Xanadu
  • Updated August 1, 2024
  • 11 minutes to read

    • The DevOps Config API provides endpoints to manage your applications.

    This API requires the DevOps Config application and is provided within the sn_devops_config namespace.

    For DELETE, PATCH, and POST operations, the calling user must have the sn_devops_config.admin role. For GET operations, the calling user must have the sn_devops_config.viewer or sn_devops_config.admin role.

    Use the DevOps Config API for application life cycle management. For more information about managing applications with DevOps Config, see Configuring DevOps Config.

    DevOps Config - DELETE /devops_config/application/{appid}

    Deletes an application.

    URL format

    Versioned URL: /api/sn_devops_config/v1/devops_config/application/{appid}

    Default URL: /api/sn_devops_config/devops_config/application/{appid}

    Supported request parameters

    Table 1. Path parameters
    Name Description
    api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

    Data type: String
    appid Sys_id of the application to delete. Located in the CDM Application [sn_cdm_application] table.

    Data type: String
    Table 2. Query parameters
    Name Description
    None
    Table 3. Request body parameters (JSON)
    Name Description
    None

    Headers

    The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

    Table 4. Request headers
    Header Description
    Accept Data format of the response body. Only supports application/json.
    Table 5. Response headers
    Header Description
    None

    Status codes

    The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

    Table 6. Status codes
    Status code Description
    200 Successful. The request was successfully processed.
    400 Bad request. Invalid application id.
    403 Forbidden. The user doesn't have permission to access the API.

    Response body parameters (JSON)

    Name Description
    error Error information. This parameter is only returned if the request failed.

    Data type: Object

    "error": { 
   "message": "String", 
   "detail": "String" 
}
    error.detail Additional details about why the request failed.

    Data type: String
    error.message Error message containing the reason the request failed.

    Data type: String
    result Result object containing information about the request.

    Data type: Object

    "result": { 
   "errors": [Array], 
   "success": [Array] 
}
    result.errors Array of errors from the request. The array is empty for successful requests.

    Data type: Array
    result.success Success message for the request. The array is empty for failed requests.

    Data type: Array
    status Status of the request. This parameter is only returned if the request failed.

    Possible value: failure

    Data type: String

    cURL request

    This example deletes an application.

    curl "https://instance.service-now.com/api/sn_devops_config/devops_config/application/38e17dc3473d111072566862736d43c7" \ 
--request DELETE \ 
--header "Accept:application/json" \ 
--user 'username':'password'

    Response body.

    { 
  "result": { 
    "errors": [], 
    "success": [ 
      "CDM Application Demo Application 1234 has been deleted successfully." 
    ] 
  } 
}

    cURL request

    This example shows an error response when a user doesn't have permission to access the API.

    curl "https://instance.service-now.com/api/sn_devops_config/devops_config/application/38e17dc3473d111072566862736d43c7" \ 
--request DELETE \ 
--header "Accept:application/json" \ 
--user 'username':'password'

    Error response.

    { 
  "error": { 
    "message": "User Not Authorized", 
    "detail": "Failed API level ACL Validation" 
  }, 
  "status": "failure" 
}

    DevOps Config - GET /devops_config/application/{appid}

    Retrieves an application.

    URL format

    Versioned URL: /api/sn_devops_config/v1/devops_config/application/{appid}

    Default URL: /api/sn_devops_config/devops_config/application/{appid}

    Supported request parameters

    Table 7. Path parameters
    Name Description
    api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

    Data type: String
    appid Sys_id of the application to retrieve. Located in the CDM Application [sn_cdm_application] table.

    Data type: String
    Table 8. Query parameters
    Name Description
    None
    Table 9. Request body parameters (JSON)
    Name Description
    None

    Headers

    The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

    Table 10. Request headers
    Header Description
    Accept Data format of the response body. Only supports application/json.
    Table 11. Response headers
    Header Description
    None

    Status codes

    The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

    Table 12. Status codes
    Status code Description
    200 Successful. The request was successfully processed.
    400 Bad request. Invalid application id.
    403 Forbidden. The user doesn't have permission to access the API.

    Response body parameters (JSON)

    Name Description
    error Error information. This parameter is only returned if the request failed.

    Data type: Object

    "error": { 
   "message": "String", 
   "detail": "String" 
}
    error.detail Additional details about why the request failed.

    Data type: String
    error.message Error message containing the reason the request failed.

    Data type: String
    result Result object containing information about the request.

    Data type: Object

    "result": { 
  "data": {Object},
  "message": "String",
  "status": Number
}
    result.data Data for the application.

    Data type: Object

    "data": { 
  "appDescription": "String", 
  "appId": "String",
  "appManagedByGroups": [Array],
  "appManufacturerId": "String", 
  "appManufacturerName": "String", 
  "appModelId": "String", 
  "appModelName": "String", 
  "appModelOwnerId": "String", 
  "appModelOwnerName": "String", 
  "appName": "String", 
  "sdlcType": "String"
}
    result.data.appDescription Description of the application.

    Data type: String
    result.data.appId Sys_id of the application. Located in the CDM Application [sn_cdm_application] table.

    Data type: String
    result.data.appManagedByGroups Comma-separated list of sys_ids of the groups that manage the application. Located in the Group [sys_user_group] table.

    Data type: String
    result.data.appManufacturerId Sys_id of the manufacturer. Located in the Company [core_company] table.

    Data type: String
    result.data.appManufacturerName Name of the manufacturer.

    Data type: String
    result.data.appModelId Sys_id of the application model. Located in the Application Model [cmdb_application_product_model] table.

    Data type: String
    result.data.appModelName Name of the application model. Located in the Application Model [cmdb_application_product_model] table.

    Data type: String
    result.data.appModelOwnerId Sys_id of the application model owner. Located in the User [sys_user] table.

    Data type: String
    result.data.appModelOwnerName Name of the application model owner.

    Data type: String
    result.data.appName Name of the application.

    Data type: String
    result.data.error Error information. This parameter is only returned if the request failed.

    Data type: String
    result.data.sdlcType The type of application.
    Possible values:
    • application
    • infrastructure

    Data type: String
    result.message Information about the successful or unsuccessful outcome of the request.

    Data type: String
    result.status Status code for the request.
    Possible values:
    • 200
    • 400
    • 403

    Data type: Number
    status Status of the request. This parameter is only returned if the request failed.

    Possible value: failure

    Data type: String

    cURL request

    This example retrieves an application.

    curl "https://instance.service-now.com/api/sn_devops_config/devops_config/application/38e17dc3473d111072566862736d43c7" \ 
--request GET \ 
--header "Accept:application/json" \ 
--user 'username':'password'

    Response body.

    { 
  "result": { 
    "status": 200, 
    "message": "Success", 
    "data": { 
      "appName": "Demo Application 1234", 
      "appId": "38e17dc3473d111072566862736d43c7", 
      "appDescription": "Updated description of Demo Application created from REST API", 
      "sdlcType": "application", 
      "appModelId": "a4e13dc3473d111072566862736d4307", 
      "appModelName": "Demo Application 1234", 
      "appManufacturerId": "262702654725d950a34a3085d36d435e", 
      "appManufacturerName": "", 
      "appModelOwnerId": "6816f79cc0a8016401c5a33be04be441", 
      "appModelOwnerName": "System Administrator", 
      "appManagedByGroups": [] 
    } 
  } 
}

    cURL request

    This example shows an error response when a user provides an invalid application id.

    curl "https://instance.service-now.com/api/sn_devops_config/devops_config/application/18a17de3283d15107256686277777777" \ 
--request GET \ 
--header "Accept:application/json" \ 
--user 'username':'password'

    Error response.

    { 
  "result": { 
    "status": 400, 
    "message": "No valid Application", 
    "data": { 
      "error": "No valid Application" 
    } 
  } 
}

    DevOps Config - PATCH /devops_config/application/{appid}

    Updates an application.

    URL format

    Versioned URL: /api/sn_devops_config/v1/devops_config/application/{appid}

    Default URL: /api/sn_devops_config/devops_config/application/{appid}

    Supported request parameters

    Table 13. Path parameters
    Name Description
    api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

    Data type: String
    appid Sys_id of the application to update. Located in the CDM Application [sn_cdm_application] table.

    Data type: String
    Table 14. Query parameters
    Name Description
    None
    Table 15. Request body parameters (JSON)
    Name Description
    appDescription Description of the application.

    Data type: String
    appManagedByGroups Comma-separated list of sys_ids of the groups that manage the application. The calling user must belong to these groups. Located in the Group [sys_user_group] table.

    Data type: String

    "appManagedByGroups": "sys_id, sys_id"
    appManufacturerId Sys_id of the manufacturer. Located in the Company [core_company] table.

    Data type: String
    appModelOwnerId Sys_id of the application model owner. Located in the User [sys_user] table.

    Data type: String

    Headers

    The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

    Table 16. Request headers
    Header Description
    Accept Data format of the response body. Only supports application/json.
    Content-Type Data format of the request body. Only supports application/json.
    Table 17. Response headers
    Header Description
    None

    Status codes

    The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

    Table 18. Status codes
    Status code Description
    200 Application successfully updated.
    403 Forbidden. The user doesn't have permission to access the API.
    404 Application not updated. The message property in the result object contains additional information about the error.

    Response body parameters (JSON)

    Name Description
    error Error information. This parameter is only returned if the request failed.

    Data type: Object

    "error": { 
   "message": "String", 
   "detail": "String" 
}
    error.message Error message containing the reason the request failed.

    Data type: String
    error.detail Additional details about why the request failed.

    Data type: String
    result Result object containing information about the application.

    Data type: Object

    "result": { 
   "message": "String", 
   "data": "String" 
}
    result.message Information about the successful or unsuccessful outcome of the request.

    Data type: String
    result.data Sys_id of the application. Located in the CDM Application [sn_cdm_application] table.

    Data type: String
    status Status of the request. This parameter is only returned if the request failed.

    Possible value: failure

    Data type: String

    cURL request

    This example updates an existing application.

    curl "https://instance.service-now.com/api/sn_devops_config/devops_config/application/38e17dc3473d111072566862736d43c7" \ 
--request PATCH \ 
--header "Accept:application/json" \ 
--header "Content-Type:application/json" \ 
--data "{ 
  \"appDescription\": \"Updated description of Demo Application created from REST API\", 
  \"appManufacturerId\": \"262702654725d950a34a3085d36d435e\", 
  \"appModelOwnerId\": \"6816f79cc0a8016401c5a33be04be441\" 
}" \ 
--user 'username':'password'

    Response body.

    { 
  "result": { 
    "message": "Application with name Demo Application 1234 updated successfully.", 
    "data": "38e17dc3473d111072566862736d43c7" 
  } 
}

    DevOps Config - POST /devops_config/application

    Creates an application.

    URL format

    Versioned URL: /api/sn_devops_config/v1/devops_config/application

    Default URL: /api/sn_devops_config/devops_config/application

    Supported request parameters

    Table 19. Path parameters
    Name Description
    api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

    Data type: String
    Table 20. Query parameters
    Name Description
    None
    Table 21. Request body parameters (JSON)
    Name Description
    appDescription Description of the application.

    Data type: String
    appManagedByGroups Comma-separated list of sys_ids of the groups that manage the application. The calling user must belong to these groups. Located in the Group [sys_user_group] table.

    Data type: String

    "appManagedByGroups": "sys_id, sys_id"
    appManufacturerId Sys_id of the manufacturer. Located in the Company [core_company] table.

    Data type: String
    appModelId Sys_id of an existing application model to use to create the application. Located in the Application Model [cmdb_application_product_model] table.

    If this parameter is provided, don't provide the appName, appModelName, appServiceName, appServiceId, or technicalServiceId parameters.

    Data type: String
    appModelName Name of an existing application model to use to create the application. Located in the Application Model [cmdb_application_product_model] table.

    If this parameter is provided, don't provide the appName, appModelId, appServiceName, appServiceId, or technicalServiceId parameters.

    Data type: String
    appModelOwnerId Sys_id of the application model owner. Located in the User [sys_user] table.

    Data type: String
    appName Name of the application.

    Don't use the same name as any existing application.

    If this parameter is provided, don't provide the appModelName, appModelId, appServiceName, appServiceId, or technicalServiceId parameters.

    Data type: String
    appServiceId Sys_id of an existing application service to use to create the application. Located in the Application Service [cmdb_ci_service_auto] table.

    Use this parameter only when the type is application.

    If this parameter is provided, don't provide the appName, appModelName, appModelId, appServiceName, or technicalServiceId parameters.

    Data type: String
    appServiceName Name of an existing application service to use to create the application. Located in the Application Service [cmdb_ci_service_auto] table.

    Use this parameter only when the type is application.

    If this parameter is provided, don't provide the appName, appModelName, appModelId, appServiceId, or technicalServiceId parameters.

    Data type: String
    technicalServiceId Sys_id of an existing dynamic CI group to use to create the application. Located in the Dynamic CI Group [cmdb_ci_query_based_service] table.

    Use this parameter only when the type is infrastructure.

    If this parameter is provided, don't provide the appName, appModelName, appModelId, appServiceName, or appServiceId parameters.

    Data type: String
    type Required. The type of application to create.
    Valid values:
    • application
    • infrastructure

    Data type: String

    Headers

    The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

    Table 22. Request headers
    Header Description
    Accept Data format of the response body. Only supports application/json.
    Content-Type Data format of the request body. Only supports application/json.
    Table 23. Response headers
    Header Description
    None

    Status codes

    The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

    Table 24. Status codes
    Status code Description
    201 Application successfully created.
    403 Forbidden. The user doesn't have permission to access the API.
    404 Application not created. The message property in the result object contains additional information about the error.

    Response body parameters (JSON)

    Name Description
    error Error information. This parameter is only returned if the request failed.

    Data type: Object

    "error": { 
   "message": "String", 
   "detail": "String" 
}
    error.message Error message containing the reason the request failed.

    Data type: String
    error.detail Additional details about why the request failed.

    Data type: String
    result Result object containing information about the application.

    Data type: Object

    "result": { 
   "message": "String", 
   "data": "String" 
}
    result.message Information about the successful or unsuccessful outcome of the request.

    Data type: String
    result.data Sys_id of the application. Located in the CDM Application [sn_cdm_application] table.

    Data type: String
    status Status of the request. This parameter is only returned if the request failed.

    Possible value: failure

    Data type: String

    cURL request

    This example creates a new application.

    curl "https://instance.service-now.com/api/sn_devops_config/devops_config/application" \ 
--request POST \ 
--header "Accept:application/json" \ 
--header "Content-Type:application/json" \ 
--data "{ 
  \"type\": \"application\", 
  \"appName\": \"Demo Application 1234\", 
  \"appDescription\": \"Description of Demo Application created from REST API\", 
  \"appManufacturerId\": \"262702654725d950a34a3085d36d435e\", 
  \"appModelOwnerId\": \"6816f79cc0a8016401c5a33be04be441\" 
}" \ 
--user 'username':'password'

    Response body.

    { 
  "result": { 
    "message": "Application with name Demo Application 1234 created successfully.", 
    "data": "38e17dc3473d111072566862736d43c7" 
  } 
}