OpenAPI: Difference between revisions

From MiRTA PBX documentation
Jump to navigation Jump to search
← Older editNewer edit →
Admin (talk | contribs)
Bureaucrats, Administrators
1,822 edits
No edit summary
No edit summary
Line 3: Line 3:
<code>openapi.php</code> is the JSON API endpoint based on the OpenAPI specification.
<code>openapi.php</code> is the JSON API endpoint based on the OpenAPI specification.


The API uses the existing MirtaPBX API keys:
The API uses the existing API keys:


* Full API key: <code>APIKEY</code>
* Full API key: <code>APIKEY</code>
Line 10: Line 10:
Both global and tenant-level keys are supported.
Both global and tenant-level keys are supported.


The first implemented API object is <code>extension</code>, with a list endpoint returning extension ID, number, name, and technology.
The first implemented API object is <code>extension</code>. It provides a list endpoint returning the extension ID, extension number, extension name, and extension technology.


== OpenAPI Specification ==
== OpenAPI Specification ==


The OpenAPI specification is available from:
The OpenAPI specification is available from:
 
 
<pre>
<pre>
openapi.php
openapi.php
Line 22: Line 22:
openapi.php/swagger.json
openapi.php/swagger.json
</pre>
</pre>
 
 
The response is an OpenAPI 3.0.3 JSON document.
The response is an OpenAPI 3.0.3 JSON document.
 
 
== Authentication ==
== Authentication ==
 
 
The API key can be provided in any of these ways.
The API key can be provided in any of these ways.
 
 
=== Query Parameter ===
=== Query Parameter ===
 
 
<pre>
<pre>
openapi.php/extensions?tenant=TENANTCODE&key=APIKEY
openapi.php/extensions?tenant=TENANTCODE&key=APIKEY
</pre>
</pre>
 
 
=== Header ===
=== Header ===
 
 
<pre>
<pre>
X-API-Key: APIKEY
X-API-Key: APIKEY
</pre>
</pre>
 
 
=== Bearer Token ===
=== Bearer Token ===
 
 
<pre>
<pre>
Authorization: Bearer APIKEY
Authorization: Bearer APIKEY
</pre>
</pre>
 
 
== API Key Scope ==
== API Key Scope ==
 
 
=== Tenant API Key ===
=== Tenant API Key ===
 
 
When using a tenant-level API key, the <code>tenant</code> parameter is required.
When using a tenant-level API key, the <code>tenant</code> parameter is required.
 
 
<pre>
<pre>
openapi.php/extensions?tenant=TENANTCODE&key=TENANT_API_KEY
openapi.php/extensions?tenant=TENANTCODE&key=TENANT_API_KEY
</pre>
</pre>
 
 
=== Global API Key ===
=== Global API Key ===
 
 
When using the global API key, <code>tenant</code> is optional.
When using a global API key, <code>tenant</code> is optional.
 
 
If <code>tenant</code> is provided, only that tenant's extensions are returned.
If <code>tenant</code> is provided, only that tenant's extensions are returned.
 
 
If <code>tenant</code> is omitted, extensions from all tenants are returned.
If <code>tenant</code> is omitted, extensions from all tenants are returned.
 
 
<pre>
<pre>
openapi.php/extensions?key=GLOBAL_API_KEY
openapi.php/extensions?key=GLOBAL_API_KEY
</pre>
</pre>
 
 
== List Extensions ==
== List Extensions ==
 
 
=== Endpoint ===
=== Endpoint ===
 
 
<pre>
<pre>
GET openapi.php/extensions
GET openapi.php/extensions
</pre>
</pre>
 
 
Alternative compatibility format:
Alternative compatibility format:
 
 
<pre>
<pre>
openapi.php?object=extension&action=list
openapi.php?object=extension&action=list
</pre>
</pre>
 
 
=== Parameters ===
=== Parameters ===


Line 91: Line 91:
|-
|-
| <code>key</code>
| <code>key</code>
| Yes, unless using header auth
| Yes, unless using header authentication
| Full or read-only API key
| Full or read-only API key
|-
|-
Line 98: Line 98:
| Tenant code or tenant name
| Tenant code or tenant name
|}
|}
 
 
=== Example Request ===
=== Example Request ===
 
 
<pre>
<pre>
curl "https://pbx.example.com/openapi.php/extensions?tenant=TENANTCODE&key=APIKEY"
curl "https://pbx.example.com/openapi.php/extensions?tenant=TENANTCODE&key=APIKEY"
Line 110: Line 110:
curl \
curl \
   -H "X-API-Key: APIKEY" \
   -H "X-API-Key: APIKEY" \
  "https://pbx.example.com/openapi.php/extensions?tenant=TENANTCODE"
</pre>
Using bearer authentication:
<pre>
curl \
  -H "Authorization: Bearer APIKEY" \
   "https://pbx.example.com/openapi.php/extensions?tenant=TENANTCODE"
   "https://pbx.example.com/openapi.php/extensions?tenant=TENANTCODE"
</pre>
</pre>
Line 115: Line 123:
=== Example Response ===
=== Example Response ===


<syntaxhighlight lang="json">
<pre>
[
[
   {
   {
Line 130: Line 138:
   }
   }
]
]
</syntaxhighlight>
</pre>


== Response Fields ==
== Response Fields ==
Line 155: Line 163:
| Extension technology, for example <code>SIP</code>, <code>PJSIP</code>, <code>VIRTUAL</code>, or <code>CUSTOM</code>
| Extension technology, for example <code>SIP</code>, <code>PJSIP</code>, <code>VIRTUAL</code>, or <code>CUSTOM</code>
|}
|}
 
 
== Error Responses ==
== Error Responses ==
 
 
Errors are returned as JSON.
Errors are returned as JSON.
 
 
=== Missing API Key ===
=== Missing API Key ===
 
 
<syntaxhighlight lang="json">
<pre>
{
{
   "error": {
   "error": {
Line 169: Line 177:
   }
   }
}
}
</syntaxhighlight>
</pre>
 
 
=== Invalid API Key ===
=== Invalid API Key ===
 
 
<syntaxhighlight lang="json">
<pre>
{
{
   "error": {
   "error": {
Line 180: Line 188:
   }
   }
}
}
</syntaxhighlight>
</pre>
 
 
=== Tenant Not Found ===
=== Tenant Not Found ===
<pre>
{
  "error": {
    "code": "tenant_not_found",
    "message": "Tenant not found."
  }
}
</pre>
=== Endpoint Not Found ===
<pre>
{
  "error": {
    "code": "not_found",
    "message": "Endpoint not found."
  }
}
</pre>
=== Method Not Allowed ===
Only <code>GET</code> is currently supported.
<pre>
{
  "error": {
    "code": "method_not_allowed",
    "message": "Only GET is supported by this endpoint."
  }
}
</pre>
== Notes ==
* Read-only API keys are allowed for the extension list endpoint.
* The endpoint does not create a web session.
* Responses are always JSON.
* CORS is enabled with <code>Access-Control-Allow-Origin: *</code>.
* <code>OPTIONS</code> requests return HTTP <code>204</code> for browser preflight support.

Revision as of 07:50, 25 May 2026

Overview

openapi.php is the JSON API endpoint based on the OpenAPI specification.

The API uses the existing API keys:

  • Full API key: APIKEY
  • Read-only API key: READONLYAPIKEY

Both global and tenant-level keys are supported.

The first implemented API object is extension. It provides a list endpoint returning the extension ID, extension number, extension name, and extension technology.

OpenAPI Specification

The OpenAPI specification is available from: 

openapi.php
openapi.php?spec=1
openapi.php/openapi.json
openapi.php/swagger.json

The response is an OpenAPI 3.0.3 JSON document.

Authentication

The API key can be provided in any of these ways.

Query Parameter

openapi.php/extensions?tenant=TENANTCODE&key=APIKEY

X-API-Key: APIKEY

Bearer Token

Authorization: Bearer APIKEY

API Key Scope

Tenant API Key

When using a tenant-level API key, the tenant parameter is required. 

openapi.php/extensions?tenant=TENANTCODE&key=TENANT_API_KEY

Global API Key

When using a global API key, tenant is optional.

If tenant is provided, only that tenant's extensions are returned.

If tenant is omitted, extensions from all tenants are returned. 

openapi.php/extensions?key=GLOBAL_API_KEY

List Extensions

Endpoint

GET openapi.php/extensions

Alternative compatibility format: 

openapi.php?object=extension&action=list

Parameters

Name Required Description
key Yes, unless using header authentication Full or read-only API key
tenant Required for tenant keys Tenant code or tenant name

Example Request

curl "https://pbx.example.com/openapi.php/extensions?tenant=TENANTCODE&key=APIKEY"

Using header authentication: 

curl \
  -H "X-API-Key: APIKEY" \
  "https://pbx.example.com/openapi.php/extensions?tenant=TENANTCODE"

Using bearer authentication: 

curl \
  -H "Authorization: Bearer APIKEY" \
  "https://pbx.example.com/openapi.php/extensions?tenant=TENANTCODE"

Example Response

[
  {
    "id": 101,
    "number": "100",
    "name": "Reception",
    "tech": "PJSIP"
  },
  {
    "id": 102,
    "number": "101",
    "name": "Office",
    "tech": "SIP"
  }
]

Response Fields

Field Type Description
id integer Extension internal ID
number string Extension number
name string Extension display name
tech string Extension technology, for example SIP, PJSIP, VIRTUAL, or CUSTOM

Error Responses

Errors are returned as JSON.

Missing API Key

{
  "error": {
    "code": "missing_api_key",
    "message": "Missing API key."
  }
}

Invalid API Key

{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid API key."
  }
}

Tenant Not Found

{
  "error": {
    "code": "tenant_not_found",
    "message": "Tenant not found."
  }
}

Endpoint Not Found

{
  "error": {
    "code": "not_found",
    "message": "Endpoint not found."
  }
}

Method Not Allowed

Only GET is currently supported. 

{
  "error": {
    "code": "method_not_allowed",
    "message": "Only GET is supported by this endpoint."
  }
}

Notes

  • Read-only API keys are allowed for the extension list endpoint.
  • The endpoint does not create a web session.
  • Responses are always JSON.
  • CORS is enabled with Access-Control-Allow-Origin: *.
  • OPTIONS requests return HTTP 204 for browser preflight support.
Retrieved from "http://www.mirtapbx.com/manual/index.php?title=OpenAPI&oldid=2014"