Landing Page

Every GET request to the Next API can return JSON or HTML. This page will focus on the JSON response coming from the Next server. Content genociated can be done in 2 ways:

part of the query part of the path /?f=json (/?f=application/json will also work)
In the request Header Accept application/json

Landing Page

Retrieves the landing page. The purpose of the landing page is to provide clients with a starting point for using the API. Any resource exposed through an API can be accessed by following paths or links starting from the landing page.

The landing page includes three metadata elements; title, description, and attribution. Only the title is required. These three elements describe the API as a whole. Clients can expect to encounter metadata which is more resource-specific as they follow links and paths from the landing page.

GET started with the landing page /?f=json

The Landing Page returns 2 parts

Body
Headers

Body

The body contains the service title and description (taken straight from the config file). The Attribution is omitted here.

{
  "title": "Service name",
  "description": "Service description (change in config.ini)",
  "attribution": "n/a",
  "serverCount": 0
}

Headers

API-Version: 1.5.9052
Link: <http://192.168.0.142:8080/v1?f=json>; rel="self"; type="application/json"; title="This document", <http://192.168.0.142:8080/v1?f=html>; rel="alternate"; type="text/html"; title="This document as HTML", <http://192.168.0.142:8080/v1/conformance>; rel="conformance"; type=""; title="conformance classes implemented by this audioVideoServer", <http://192.168.0.142:8080/v1/openapi.json>; rel="service-desc"; type="application/json"; title="Definition of the API in OpenAPI 3.0", <http://192.168.0.142:8080/v1/openapi.yaml>; rel="service-desc"; type="application/vnd.oai.openapi+json;version=3.0"; title="Definition of the API in OpenAPI 3.0", <http://192.168.0.142:8080/v1/servers>; rel="data"; type=""; title="Access the server collection"
Content-Type: application/json
Content-Length: 119
X-Powered-By: dotNetExpress
Connection: Close
Date: Wed, 16 Oct 2024 14:06:10 GMT

The Link header contains some interesting links:

<http://192.168.0.142:8080/v1?f=json>; rel="self"; type="application/json"; title="This document",
<http://192.168.0.142:8080/v1?f=html>; rel="alternate"; type="text/html"; title="This document as HTML", 
<http://192.168.0.142:8080/v1/conformance>; rel="conformance"; type=""; title="conformance classes implemented by this audioVideoServer",
<http://192.168.0.142:8080/v1/openapi.json>; rel="service-desc"; type="application/json"; title="Definition of the API in OpenAPI 3.0",
<http://192.168.0.142:8080/v1/openapi.yaml>; rel="service-desc"; type="application/vnd.oai.openapi+json;version=3.0"; title="Definition of the API in OpenAPI 3.0",
<http://192.168.0.142:8080/v1/servers>; rel="data"; type="servers"; title="Access the server collection"

Do not hardcode the paths to the api or server in your application, instead get the path from the links received from the landing page.

So to get the URI of servers, search the list of returned URIs where rel equals "data"

API

/openapi?f=json

Retrieves the API definition which describes the capabilities provided by that API. This resource can be used by developers to understand the API, by software clients to connect to the server, and by development tools to support the implementation of servers and clients.

Conformance

/conformance?f=json

Provides a list declaring the modules that are implemented by the API. These modules are referred to as Conformance Classes. The list of Conformance Classes is key to understanding and using the Nexa API.