In this article, we will take a detailed look into one POST method API that will, say, help you to make an operation on the service instances (operations such as Suspend, Resume, Terminate). With the appropriate input parameters (say, JSON), you can perform an operation on a service instance that is (say) in the suspended (resumable) to terminated state. Similarly, there are few POST methods under each service group using which you can perform operations directly using the API service calls.
Let's take a detailed look into the different sections in the POST Method -
- GET/POST - Displays the type of method used by the service. If it is a GET method, you will notice GET. If it is a POST method, you will notice a POST.
- Service Name - Displays the Name of the backend REST service
- Service Name (hyperlink) - Click to expand/collapse the service details section
- Implementation Notes - Provides detailed information about what the service will do. In this case, the implementation notes provide information such as the selected API will perform the chosen operation on the service instance, say, Suspend, Resume, or Terminate.
Response Class - This section displays the sample of the response (an Example JSON) that you will see after you execute the API. If the API was successfully able to perform the operation, you will see a response status with "success: true".
You have the option of viewing the detailed schema (with explanation) of the response code by clicking on the Schema link.
- Response Content Type - Choose the response content type that you would like to see from the drop down (for instance, application/json)
Parameters - Before actually implementing the API for your custom purpose, you can actually visualize the output that you will see if you execute the API. To try this out, the Parameters section plays an important role. To execute a POST method, you need to specify a JSON input with the values for the corresponding fields.
- Parameter - Specifies the list of parameters that are required as an input for the API. In this case, the API requires a Request JSON to be able to perform an operation on the service instance.
- Value - Enter the JSON in the space provided. For ease of use, we have provided an Example JSON (under Data Type parameter) with dummy values. Simply click on the Example JSON to copy the JSON to the 'Values' text box. Now you can replace the dummy values with the actual values.
- Parameter content type - Select the type of parameter value that you are entering the 'Value' section. If it is a JSON, select application/json from the drop down.
- Description - Provides a detailed description about the parameter that has to be provided as an input value for the API
- Parameter Type - Specifies the type of the parameter that is being given as the input, for instance, body
Data Type - There are two options - Schema and Example JSON. Schema provides the schema definition of the JSON file that is being provided as the input to the API. Example JSON gives a sample JSON that you can easily copy to the 'Values' text box by clicking on it. You can later customize the JSON with your required information that the API will actually create.
Try it out
Click the Try it out! button to see the actual response from the API service call.
- Request URL - Displays the URL (API) that is passed to the BizTalk server to retrieve the information, in this case, to execute the service instance operation
- Response Body - If the API was successfully able to perform the selected operation (say, terminate a suspended service instance), you will see a response status with "success: true". Otherwise, you will notice the response status with "success:false" and an exception message regarding the error.
- Response Code - The response code will display the value as 200 if the API was successfully able to perform the operation on the service instance (terminating a suspended service instance in this case)
- Response Headers - Displays the response headers for the API call that retrieves the information from the BizTalk server
- Hide Response - Click the link to Hide the response section beneath the Try it out! button