API Endpoints

Adding API Endpoints

There are two means of adding endpoints for an API. The recommended method is to upload an API specification document. The API specification must be in either JSON or YAML format and must be Open API 3.0 or Swagger 2.0 compliant. Additionally, if you do not have an API specification document you can add endpoints individually.

API Specification Document Details

If you have an API specification document for your API, you can upload it to configure all of the endpoints included in the API specification document. The API specification document must be in JSON or YAML format and it must be Open API 3.0 or Swagger 2.0 compliant. Additionally, we support 'Postman collections' in JSON format, either by upload in the WhiteHat Portal, or sent raw via the API.

Postman Collection Details

Postman is now supported either by file upload via Sentinel, or by the raw collection JSON (YAML not yet supported) via the API at POST /api/apiAssets/{siteID}/endpoints.

As the Auto API process stores and manipulates API documentation in OpenAPI 3 format, the Postman collection is converted, which means functionality that is not supported by OpenAPI 3 will cause errors. Most notably, requests with methods outside of GET, PUT, PATCH, POST, DELETE, HEAD, OPTIONS, TRACE, and CONNECT will cause errors. Collection level variables are supported. Additionally, the Postman collection schema allows for folder, request and URL variables which are also supported.

Some limitations exist:

  • Authorization configured in the Postman collection is not applied on upload, but rather it must be manually configured in the WhiteHat Portal.

  • The environment variables and the global variables do not get exported with the collection. This means that any field that contains references to global or environment variables must be manually updated, which can be done via the WhiteHat Portal UI.

  • The pre-request script section from the request is not parsed.

  • Content-Type for request body is not detected based on the raw body (OpenAPI specification pairs each request body with a type which will be defaulted to application/json if not provided). If a Content-Type header exists for that request, that content type will be used instead. Requests with either form-data or x-www-form-urlencoded will have their type identified automatically.

Uploading an API Specification Document

To upload an API specification document, perform the following steps:

  1. Click the Add Endpoints button.

    api endpoints upload 1

  2. Select Upload Documentation from the dropdown list.

  3. Either drag and drop your file to the Upload Documentation box that is displayed or browse to the file location.

    api endpoints upload 2

  4. Select one of the three upload options:

    1. Merge endpoints - Add new endpoints and updated endpoints in documentation.

    2. Add endpoints - Add new endpoints in documentation

    3. Overwrite endpoints - Overwrite existing endpoints with endpoints in documentation

  5. Click on the Upload button.

Each of the endpoints included in the API specification document are now displayed in the endpoint list.

  • Enabled by default: GET, HEAD, TRACE and OPTION.

  • Disabled by default: PUT, POST, DELETE and PATCH.

Endpoints that require further configuration are identified by the information icon. This usually means that a required parameter does not have a default value provided. You can click on the endpoint to resolve the issue.

Adding an Individual Endpoint

  1. Click the Add Endpoints button.

    api endpoints individual 1

  2. Select Individual from the dropdown list. The endpoint configuration screen is now displayed, where you can populate the fields for the endpoint that you are defining.

    api endpoints individual 2

  3. In the Summary field, provide a brief overview of your endpoint.

  4. In the Description field, provide a full description of your endpoint.

  5. In the Operation ID field, provide a unique identifier for the endpoint.

  6. In the endpoint method field, select a method for the endpoint from the dropdown. You can choose GET, PUT, POST, DELETE, OPTIONS, HEAD, PATCH, or TRACE.

  7. In the endpoint path field, provide a path for the endpoint. The primary hostname URL is automatically populated, so you must provide the URL for the specific endpoint that you are defining.

  8. If your endpoint uses parameters, you can add these by clicking on the Add Parameter button. This displays additional fields for you to populate with values.

    [width="90%"

  9. Ensure that you are on the Parameters tab.

    1. Insert the name of your parameter in the Name field.

    2. The Default Value field displays the default value for the parameter. This is a mandatory field for any required parameter.

    3. The In field defines what the parameter value is obtained from. From this dropdown list, choose from Query, Header, Path, or Cookie.

    4. Provide a full description of your parameter in the Description field.

    5. Click on the trash/bin symbol beside any parameter to delete it.

  10. The Request Body tab enables the user to add and define request bodies.

    Request bodies are typically used with create and update operations (POST, PUT, PATCH). For example, when creating a resource using POST or PUT, the request body usually contains the representation of the resource to be created.

  11. The Responses tab displays the response(s) defined for that particular operation. You cannot modify a response in this tab. An API specification must specify the responses for all API operations. Each operation must have at least one response defined, which is usually a successful response. A response is defined by its HTTP status code and the data returned in the response body and/or headers.

  12. Use the Test button to build the entire endpoint from all the information that you have provided. This calls the endpoint and the request and the response are displayed in the text boxes at the bottom of the page and provide useful information for troubleshooting any issues with the endpoint configuration.

  13. Click the Save button to save all the information provided.

Editing API Endpoints

To enable or edit an existing endpoint:

  1. Locate the endpoint that you wish to enable or edit from the endpoint list. You can search the endpoint list by typing in the Search field at the top of the list. This filters the list to only display endpoints where the endpoint URL contains the text typed.

    api endpoints search

  2. You can enable or disable an endpoint easily by switching the Enable slider for each endpoint in the list.

  3. Update the endpoint details as required.

  4. Click the Save button.

Deleting API Endpoints

  1. Locate the endpoint that you wish to delete from the endpoint list. You can search the endpoint list by typing in the Search field at the top of the list. This filters the list to only display endpoints where the endpoint URL contains the text typed.

    api endpoints delete

  2. Click the ellipsis for the endpoint that you wish to delete.

  3. From the options displayed, select Delete.

  4. When prompted, click Confirm to complete the deletion.

    api endpoints delete 2