API interface architecture

Each API Service Endpoint can potentially implement a different set of HTTP request methods. For more information about the methods generally supported within IBM Telco Network Cloud Manager - Orchestration, see the following table.

The following table describes HTTP response codes that can be returned in various error scenarios. Any client must expect that any API call can return these codes under exceptional circumstances.

Error responses can be generated by IBM Telco Network Cloud Manager - Orchestration.

• All IBM Telco Network Cloud Manager - Orchestration API calls return the following information in the Response Body when an error is encountered, for example, for a 40x, 50x Response Code:

  {
    "details": {},
    "localizedMessage": "string",
    "url": "string"
  }

  The Response Body content type is application/json

  The response properties are described in the following table.

  Table 3. Response properties

  Property Name	Description	Mandatory
  details	Any additional information that is related to the error that might be useful during debugging.	Yes
  localizedMessage	The description of the error that occurs.	Yes
  url	The URL of the root cause of the problem or null if unknown.	No

  A more fully populated error report from IBM Telco Network Cloud Manager - Orchestration looks like this:

  {
    "url": /api/resource-manager/configuration/923227664489862,
    "localizedMessage": "A FATAL IBM Telco Network Cloud Manager -
  Orchestration Driver error has occurred: Unknown Resource Manager 923227664489862",
    "details": {
      "responseHttpStatus": 500,
      "errorStatus": "FATAL",
      "responseData": {
        "url": "http://galileo:8283/api/topology/resource-managers/923227664489862";,
        "localizedMessage": "Unknown Resource Manager 923227664489862",
        "details": {}
      }
    }
  }

  More than one set of error details might be included. The error reports show the errors that are generated by components internal to IBM Telco Network Cloud Manager - Orchestration and passed back through the layers of requests that were made.

  If a support call becomes necessary, include all the information from any IBM Telco Network Cloud Manager - Orchestration error reports because that greatly helps with tracking the root cause of the problem.

• Rarely, an error might occur within IBM Telco Network Cloud Manager - Orchestration that for whatever reason cannot be handled gracefully, and for which an IBM Telco Network Cloud Manager - Orchestration error response is not available, for example:

  {
    "timestamp": "2017-08-10T15:28:19.586+0000",
    "status": 500,
    "error": "Internal Server Error",
    "exception": "org.springframework.web.client.ResourceAccessException",
    "message": "I/O error on GET request for \"http://9.20.64.abc:8295/api/resource-manager/configuration\": 9.20.64.abc; nested exception is java.net.UnknownHostException: 9.20.64.abc",
    "path": "/api/resource-managers"
  }

Within the header of the HTTP response received in reply to an HTTP request, is a three-digit decimal status code. The first digit of the status code specifies one of the five standard classes of responses.

1. 1xx Informational responses
2. 2xx Success
3. 3xx Redirection
4. 4xx Client errors
5. 5xx Server errors

For example, given this request:

http://<hostname>:<Port>/api/resource-manager/configuration/9.20.64.abc

The Service Endpoint is:

http://<hostname>:<Port>/api/resource-manager/configuration

For REST-style requests, an HTTP 404 is returned if the entire requested service URL (including any variable parameters) does not exist which might be for one of the following reasons.

1. The Service Endpoint that is requested does not exist or is not available (check your hostname and ports).
2. The requested resource (as identified by the URL variable parameters) does not exist.

The following examples are where an HTTP 409 status code is used within IBM Telco Network Cloud Manager - Orchestration:

1. Data constraint violations
2. Concurrent modification exceptions.

The API is divided into four sections. These provide access to the different functions provided by IBM Telco Network Cloud Manager - Orchestration. This API is called by external OSS systems to do both fulfillment tasks and some fault management tasks.

1. Assembly Orchestration. IBM Telco Network Cloud Manager - Orchestration enables the creation of Assemblies. Assemblies enable services to be created by IBM Telco Network Cloud Manager - Orchestration which interact with resource managers to create and manage virtual resources that need to be provided for the service to work. This part of the API includes two endpoints. The first enables the External OSS system to request a transition against an assembly instance, including requesting a new assembly instance. The second enables the External OSS to poll IBM Telco Network Cloud Manager - Orchestration to find out the state of the request.
2. Asynchronous Events. In response to Assembly Orchestration requests, IBM Telco Network Cloud Manager - Orchestration also puts messages on a Kafka bus. These messages describe the key events that occur during the processing of the request. It also puts a message to indicate when the processing is complete. It is recommended that the External OSS uses this mechanism to check the state of requests rather than using the polling interface defined in the previous section.
3. Assembly Topology. The external OSS might need details of the assembly instances and of the components that it is comprised. The assembly topology contains a hierarchy of the components of an assembly. A component might be either a resource or an assembly. It is also possible to request details of the events used during the assembly’s life.
4. Resource Manager Handling. Resource Managers are responsible for managing the actual resources that needed for a service to work. IBM Telco Network Cloud Manager - Orchestration needs to be told which resources managers it interface to. This process is known as Onboarding a Resource Manager. The IBM Telco Network Cloud Manager - Orchestration API provides a set of calls that enables a new resource manager instance to be on-boarded to IBM Telco Network Cloud Manager - Orchestration, and also removed from IBM Telco Network Cloud Manager - Orchestration. When a resource manager is on-boarded, the set of resource types and locations that they manage are extracted by using the Resource Manager API. The API also provides an endpoint that makes IBM Telco Network Cloud Manager - Orchestration request the associated resource manager for a set of updated resources. Any existing resources remain unchanged when this update occurs.

The media types supported by the IBM Telco Network Cloud Manager - Orchestration API are listed:

• application/hal+json
• application/octet-stream
• text/plain
• application/xml
• text/xml
• application/x-www-form-urlencoded
• application/*+xml
• multipart/form-data
• **application/json**
• **application/\*+json**