Using the API

The Oracle Dyn Web Application Security API is a typical REST API that uses HTTPS requests and responses. This topic describes basic information about using the APIs.

For a list of available methods, please see the in-portal API documentation.

API Reference and Endpoints

All requests can be made through the following endpoint:

https://dojo.zenedge.com/api/v3/

Example URI:

https://dojo.zenedge.com/api/v3/company/webapps

Create an API Application

To use the API, you will need to create an API application within your company.

Receiving the oAuth Token

An authorization token must be passed along with each request to the API. To receive the authorization token, make a POST request to https://dojo.zenedge.com/api/oauth/token, supplying the Client ID and Client Secret keys for the API application. Tokens are valid for 7200 seconds (2 hours).

Example Request

curl -F client_id=<Client ID>  -F client_secret=<Client Secret>
-X POST https://dojo.zenedge.com/api/oauth/token

Example Response

{"access_token API_TOKEN", "token_type":"bearer", "expires_in":7200, "scope":"public"}

Using the API

The Oracle Dyn Web Application Security API uses standard HTTP requests and responses.

Header

Each request header must contain a User-Agent field and an authorization token. Requests with no User-Agent header will receive a 403 Forbidden response. For support reasons, please include your username or the name of your application in the User-Header field.

Example Request:

curl -X "GET" "https://dojo.zenedge.com/api/v3/company/webapps" \
-H "Authorization: Bearer <TOKEN_Received_in_oauth>"

For a list of available methods, please see the in-portal API documentation.

Response Codes

The API only allows 500 requests per one hour from one IP address for any API request. Cache purging requests are limited to 20 per one hour. The status of your current rate limit can be found in the headers of your response.

HTTP Status Code Response Code Description
200 OK Your request was successful.
201 Created Your POST request was successful and the resource was created.
202 Accepted Your request was successful and the system is working to complete your request. Return the change_id to check status.
206 Partial Content Response returned partial content. Partial content can be paged through.
401 Unauthorized Invalid authentication details are provided.
403 Forbidden Authentication succeeded but the user does not have access to this resource.
422 Unprocessable Entity Validation error.
429 Too Many Requests Request was rejected due to rate limiting.

Rate Limiting

The API only allows 500 requests per one hour from one IP address for any API request. Cache purging requests are limited to 20 per one hour. The status of your current rate limit can be found in the headers of your response.

Header Description
X-RateLimit-Limit The maximum number of requests permitted per hour.
X-RateLimit-Remaining The number of requests remaining in the current rate limit period.
X-RateLimit-Reset The number of seconds left in the current rate limit period.

Example Response

All responses are returned as JSON objects, including errors. This is an example of the GET /webapps/:webapp_id/good_bots method, which returns a list of whitelisted bots.

200
[ { id: "d1d6d40b9c7a4276afeb46268ca16091", name: "Baidu Spider", enabled: true, description: "Baiduspider is a robot of Baidu Chinese search engine." }, { id: "f2edfc62f4374f7096c3d83256f7297a", name: "MSN Bot/BingBot", enabled: false, description: "Bingbot is Microsot's Bing search engine's crawler." } ]