Changing a REST API

You use the details page of the REST API to refractor your existing documentation.

The following general guidelines apply when refractoring the existing API documentation:

If you are not the owner of the REST API, you cannot transform the API documentation unless you have Modify permission on the API (granted though either a role-based permission or instance-level permission). For more information about roles and permissions, see Getting Started with CentraSite.

If you are viewing the API details page, you can choose to display in Resources view and Methods view. The Methods view is set by default.

When you are viewing the resources and methods, you can delete one or more of the top level REST details - resources and methods by using the Delete icon. For more information about resources and methods and the Delete option, see Viewing the Details of a REST API.

However, if you are editing the resources and methods, then you can delete the remaining resources and methods, namely - request parameters, status codes and sample requests and responses.

If you want to edit the resources and methods, ensure that the Resources and Methods profile of the API is selected in the edit mode by using the Edit icon in the action bar for the API.

In the edit mode, you will only see an editable user interface of the Resource-Centric View. There is no Method-Centric View in the edit mode.

If you are editing the API details page, you can modify one or more of the existing entities - resources, methods, request parameters, HTTP requests, HTTP responses, and the sample requests and responses; also you can delete these entities by using the Delete icon.

Currently, CentraSite supports only specific properties of RAML and Swagger specifications. For example, if the Swagger specification includes a swagger version property, you cannot define the swagger's version in the API documentation. For a list of the supported RAML or Swagger to CentraSite REST API mappings, see Importing a RESTful API to CentraSite.

Beginning with version 9.7, CentraSite supports the enhanced interface for REST APIs (in contrast, earlier versions of CentraSite supported a standardized interface for REST Service). Documentation of the prior REST service interface is available to CentraSite customers who have a current maintenance contract in Empower Product Support website.

If You Migrate REST APIs from a Pre-9.7 Release: If you have REST APIs that were created prior to CentraSite version 9.7, these REST APIs will continue to hold the version's metadata in the enhanced REST Service interface implemented by current version of CentraSite.

If You Migrate REST APIs from a 9.7 Release: If you have REST APIs that were created in the CentraSite version 9.7 using the CentraSite Business UI, these REST APIs will again continue to hold the version's metadata in the enhanced REST Service interface implemented by current version of CentraSite. However, you will find the following information in the migrated REST API:

The sample request and response messages that existed under the REST Method display without changes.

The status codes that existed under the REST Method will now display under the REST Response.

Note:

Beginning with version 9.8, although CentraSite supports the existing REST Sample Requests and Responses, we enforce you use the REST Requests and REST Responses to specify additional details about the REST payload. You may use the Sample Requests and Responses if required.