ViewLogicTechnical CenterViewLogic website
Learning paths

Your first API request to your installation

An integration developer's course for BOX 3.2: check your installation's OpenAPI schema, request API status, read the current user and interpret responses and errors.

BOX 3.2 · Integration developer

Your result

Two read requests checked against your installation's schema, with a short contract record for the next integration step.

Before you start

  • A BOX 3.2 training installation and its address from your administrator. You need Swagger access and an account permitted to make the selected requests.
  • A browser and an HTTP client, such as Swagger UI, curl or your usual tool. Basic knowledge of HTTP, JSON and the Authorization header.
  • The OpenAPI schema for this exact build. Check that the methods exist before running the examples.

The request paths below are documented for BOX 3.x. Methods, authentication and responses depend on the build and permissions. For BOX 5.0, start with its separate reference and your installation's OpenAPI schema; this course does not claim that these paths apply to BOX 5.0.

Open the schema for the installed version

Find the contract you will use to construct requests.

  1. Open /api/docs/ on your installation. If needed, download its OpenAPI schema from /api/swagger.json.
  2. Find GET /api/base/ping/ and GET /api/statistics/auth/me/. Read the authentication requirements, parameters and response descriptions.
  3. Record the installation version and the date you retrieved the schema. If a method is absent, check the installed features and choose a supported request with your administrator.
Checkpoint

Both methods are present in the current schema, and you know how to access them and which responses to expect.

If you get stuck

Swagger may fail to open because of the address, routing, permissions or installed features. An example cannot replace the schema of the running installation.

Check API availability

Make your first read request and compare its response with the schema.

  1. Replace <box-host> with your training installation's address. Make the request in Swagger or an HTTP client; include authentication if your schema requires it.
  2. Record the HTTP status and response body. Compare them with the method description in OpenAPI.
curl 'https://<box-host>/api/base/ping/'
Checkpoint

You received a response from the intended installation and compared its status and format with the method's contract.

If you get stuck

Distinguish a network error, an HTTP response and an application error in the body. A successful ping does not establish access to cameras, events or other resources.

Check authentication by reading the profile

Confirm which account is making the requests.

  1. Authenticate in Swagger according to your installation's schema. The published guide describes OAuth2 Password Flow through POST /api/statistics/auth/login/; take its fields and requirements from your OpenAPI schema.
  2. Call GET /api/statistics/auth/me/. In a client outside Swagger, send the token in the Authorization: Bearer header.
  3. Compare the current-user details with the training account. Keep only the technical information needed for the exercise; exclude tokens, passwords and personal data.
curl -H 'Authorization: Bearer <access_token>' \
  'https://<box-host>/api/statistics/auth/me/'
Checkpoint

The response agrees with the schema and the intended account. You understand the authentication method and the account's access limits.

If you get stuck

If access is denied, check token expiry and permissions using your installation's rules. Keep the status code and error description so you can distinguish an authentication problem from a missing method.

Record the contract for your next request

Prepare to read the data your integration needs.

  1. Choose a supported read method in OpenAPI, for example for cameras or events. Record its exact path and required permissions; methods differ between builds.
  2. Check filters, pagination, time formats and identifiers. If there is no data yet, agree a test record on the training installation.
  3. Use the actual schema to describe a normal response, an empty result and an access error. Keep any further requests within your account's permissions.
Checkpoint

The next method has a defined input, response, permission set and error handling. Any uncertain fields are listed for clarification.

If you get stuck

An example event structure explains field meaning. The transport, exact JSON and recipient address come from the contract of the particular integration.

Try it yourself

Investigate an authentication failure

On the training installation, call a read method that requires authentication without supplying a token. Compare the actual response with the error described in OpenAPI.

Check: You can identify the status and reason for denial, then repeat the same request with valid authentication. Exercise notes contain no passwords or tokens.

Plan list processing

Using the selected method's schema, describe how to handle nonempty and empty results and how to request the next page if pagination is supported.

Check: Use the exact schema fields. Distinguish no data from a failed request, and clarify time units and sort order.

Record your result

  • Installation version and the date of the OpenAPI schema used.
  • Methods, parameters and required permissions for the requests made.
  • Actual HTTP statuses and example responses without secrets or personal data.
  • Rules for handling empty results, access errors and network failures.
  • The next request's contract and unresolved integration questions.

Continue learning