mirrors/flexisip-account-manager
1
0
Fork 0
mirror of https://gitlab.linphone.org/BC/public/flexisip-account-manager.git synced 2026-01-17 10:08:05 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Fix #114 Complete the API documentation for the currently implemented statistics endpoint

Browse source
This commit is contained in:
Timothée Jaussoin 2023-08-23 14:37:21 +00:00
parent 99e6505b9b
commit 5fd6766a8e
5 changed files with 222 additions and 32 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

57
flexiapi/public/css/style.css vendored
View file

@ -177,12 +177,18 @@ content {
}
body.welcome content {
min-height: calc(100vh - 17rem);
min-height: calc(100vh - 18rem);
align-items: center;
margin: 0 auto;
max-width: 1024px;
}
@media screen and (max-width: 800px) {
body.welcome content {
min-height: calc(100vh - 16rem);
}
}
hr {
border-bottom: 1px solid var(--grey-3);
margin: 2rem 0;
@ -245,7 +251,7 @@ ul.tabs li.current {
header nav {
padding: 3rem 1rem;
display: flex;
min-height: 6rem;
min-height: 5rem;
}
header nav a {
@ -261,20 +267,6 @@ header nav a i {
font-size: 2.5rem;
}
@media screen and (max-width: 800px) {
header nav {
padding: 1rem;
}
header nav a {
padding: 1rem;
}
header nav a i {
margin-right: 0;
}
}
header nav a#logo {
font-weight: 700;
padding-left: 2rem;
@ -324,6 +316,25 @@ header nav a.oppose ~ a.oppose {
margin-left: 0;
}
@media screen and (max-width: 800px) {
header nav {
padding: 1rem;
}
header nav a,
header nav a#logo {
padding: 1rem;
}
header nav a#logo::before {
margin-right: 0;
}
header nav a i {
margin-right: 0;
}
}
/** Section **/
content section {
@ -464,7 +475,7 @@ content > nav a i {
/** Footer **/
body.welcome::after {
background-position: bottom center;
background-position: top center;
background-repeat: repeat-x;
background-image: url('../img/footer.svg');
display: block;
@ -472,7 +483,8 @@ body.welcome::after {
width: 100%;
background-size: 50rem;
content: '';
height: 9rem;
height: 5rem;
margin-top: 2rem;
}
/** Titles **/
@ -485,6 +497,11 @@ h1 {
display: flex;
align-items: center;
margin-right: 1rem;
margin-bottom: 1rem;
}
header > h1 {
margin-bottom: 0;
}
h1 i {
@ -558,6 +575,10 @@ ul + h1, ul + h2, ul + h3, ul + h4, h3 + p {
background-color: var(--color-yellow);
}
.badge.badge-error {
background-color: var(--color-purple);
}
/** Table **/
table {

2
flexiapi/resources/views/about.blade.php
View file

@ -11,6 +11,8 @@
<p><a href="{{ config('app.terms_of_use_url') }}">Terms and Conditions</a> and <a
href="{{ config('app.privacy_policy_url') }}">Privacy policy</a></p>
<p><a href="{{ route('api') }}">API Documentation</a> and <a href="{{ route('account.documentation') }}">General Documentation</a></p>
<p>GNU General Public Licence v3.0 (Licence)</p>
<p>{{ config('instance.copyright') }}</p>

4
flexiapi/resources/views/account/documentation.blade.php
View file

@ -1,6 +1,8 @@
@extends('layouts.main')
@extends('layouts.main', ['welcome' => true])
@section('content')
<div>
{{-- This view is only a wrapper for the markdown page --}}
{!! $documentation !!}
</div>
@endsection

4
flexiapi/resources/views/account/documentation_markdown.blade.php
View file

@ -40,7 +40,7 @@ Once activated {{ $app_name }} will ask your to provide a password to finish you
To authenticate please fill in the username or phone number and password you provided during the registration phase.
If you forgot your password or didn't configured it, you can always recover your account using the recover password forms, using your @if (config('app.web_panel')) [email address]({{ route('account.login_email') }}) @else email address @endif or @if (config('app.web_panel') && config('app.phone_authentication')) [phone number]({{ route('account.login_phone') }}) @else phone number (not enabled) @endif. Once authenticated you will then be able to change your password.
If you forgot your password or didn't configured it, you can always recover your account using the recover password forms, using your @if (config('app.web_panel')) [email address]({{ route('account.recovery.show.email') }}) @else email address @endif or @if (config('app.web_panel') && config('app.phone_authentication')) [phone number]({{ route('account.recovery.show.phone') }}) @else phone number (not enabled) @endif. Once authenticated you will then be able to change your password.
## Code based authentication
@ -68,7 +68,7 @@ Your account can be deleted from the panel using the @if (config('app.web_panel'
*The feature is not enabled on this instance.*
@endif
From the @if (config('app.web_panel'))[devices management panel]({{ route('admin.account.device.index') }}) @else devices management panel @endif an admin will be able to list and delete the devices attached to a SIP account.
From the devices management panel an admin will be able to list and delete the devices attached to a SIP account.
# Admin panel

183
flexiapi/resources/views/api/documentation_markdown.blade.php
View file

@ -8,7 +8,6 @@ A `content-type` and `accept` HTTP headers are REQUIRED to use the API properly
```
> GET /api/{endpoint}
> from: sip:foobar@sip.example.org
> content-type: application/json
> accept: application/json
```
@ -74,7 +73,9 @@ You can find more documentation on the related [IETF RFC-7616](https://tools.iet
## Ping
### `GET /ping`
<span class="badge badge-success">Public</span>
Returns `pong`
## Account Creation Request Tokens
@ -82,6 +83,7 @@ Returns `pong`
An `account_creation_request_token` is a unique token that can be validated and then used to generate a valid `account_creation_token`.
### `POST /account_creation_request_tokens`
<span class="badge badge-success">Public</span>
Create and return an `account_creation_request_token` that should then be validated to be used.
@ -91,7 +93,9 @@ Create and return an `account_creation_request_token` that should then be valida
An `account_creation_token` is a unique token that allow the creation of a **unique** account.
### `POST /account_creation_tokens/send-by-push`
<span class="badge badge-success">Public</span>
Create and send an `account_creation_token` using a push notification to the device.
Return `403` if a token was already sent, or if the tokens limit is reached for this device.
Return `503` if the token was not successfully sent.
@ -103,7 +107,9 @@ JSON parameters:
* `pn_prid` the push notification unique id
### `POST /account_creation_tokens/using-account-creation-request-token`
<span class="badge badge-success">Public</span>
Create an `account_creation_token` using an `account_creation_request_token`.
Return an `account_creation_token`.
Return `404` if the `account_creation_request_token` provided is not valid or expired otherwise.
@ -113,6 +119,7 @@ JSON parameters:
* `account_creation_request_token` required
### `POST /account_creation_tokens`
<span class="badge badge-warning">Admin</span>
Create and return an `account_creation_token`.
@ -120,13 +127,17 @@ Create and return an `account_creation_token`.
## Auth Tokens
### `POST /accounts/auth_token`
<span class="badge badge-success">Public</span>
Generate an `auth_token`. To attach the generated token to an account see [`auth_token` attachement endpoint](#get-accountsauthtokenauthtokenattach).
Return the `auth_token` object.
### `GET /accounts/auth_token/{auth_token}/attach`
<span class="badge badge-info">User</span>
Attach a publicly generated authentication token to the currently authenticated account.
Return `404` if the token is non existing or invalid.
@ -135,10 +146,11 @@ Return `404` if the token is non existing or invalid.
### `POST /accounts/public`
@if(config('app.dangerous_endpoints'))**Enabled on this instance**@else**Not enabled on this instance**@endif
@if(!config('app.dangerous_endpoints'))<span class="badge">Disabled</span>@endif
<span class="badge badge-success">Public</span>
<span class="badge badge-warning">Unsecure endpoint</span>
<span class="badge badge-error">Unsecure endpoint</span>
Create an account.
Return `422` if the parameters are invalid.
Send an email with the activation key if `email` is set, send an SMS otherwise.
@ -154,7 +166,9 @@ JSON parameters:
* `account_creation_token` the unique `account_creation_token`
### `POST /accounts/with-account-creation-token`
<span class="badge badge-success">Public</span>
Create an account using an `account_creation_token`.
Return `422` if the parameters are invalid or if the token is expired.
@ -167,25 +181,31 @@ JSON parameters:
* `dtmf_protocol` optional, values must be `sipinfo`, `sipmessage` or `rfc2833`
### `GET /accounts/{sip}/info`
<span class="badge badge-success">Public</span>
Retrieve public information about the account.
Return `404` if the account doesn't exists.
### `GET /accounts/{phone}/info-by-phone`
@if(config('app.dangerous_endpoints'))**Enabled on this instance**@else**Not enabled on this instance**@endif
@if(!config('app.dangerous_endpoints'))<span class="badge">Disabled</span>@endif
<span class="badge badge-success">Public</span>
<span class="badge badge-warning">Unsecure endpoint</span>
<span class="badge badge-error">Unsecure endpoint</span>
Retrieve public information about the account.
Return `404` if the account doesn't exists.
Return `phone: true` if the returned account has a phone number.
### `POST /accounts/recover-by-phone`
@if(config('app.dangerous_endpoints'))**Enabled on this instance**@else**Not enabled on this instance**@endif
@if(!config('app.dangerous_endpoints'))<span class="badge">Disabled</span>@endif
<span class="badge badge-success">Public</span>
<span class="badge badge-warning">Unsecure endpoint</span>
<span class="badge badge-error">Unsecure endpoint</span>
Send a SMS with a recovery PIN code to the `phone` number provided.
Return `404` if the account doesn't exists.
@ -195,10 +215,12 @@ JSON parameters:
* `account_creation_token` the unique `account_creation_token`
### `GET /accounts/{sip}/recover/{recover_key}`
@if(config('app.dangerous_endpoints'))**Enabled on this instance**@else**Not enabled on this instance**@endif
@if(!config('app.dangerous_endpoints'))<span class="badge">Disabled</span>@endif
<span class="badge badge-success">Public</span>
<span class="badge badge-warning">Unsecure endpoint</span>
<span class="badge badge-error">Unsecure endpoint</span>
Activate the account if the correct `recover_key` is provided.
The `sip` parameter can be the default SIP account or the phone based one.
@ -208,7 +230,9 @@ Return the account information (including the hashed password) if valid.
Return `404` if the account doesn't exists.
### `POST /accounts/{sip}/activate/email`
<span class="badge badge-success">Public</span>
Activate an account using a secret code received by email.
Return `404` if the account doesn't exists or if the code is incorrect, the validated account otherwise.
JSON parameters:
@ -216,7 +240,9 @@ JSON parameters:
* `confirmation_key` the confirmation key
### `POST /accounts/{sip}/activate/phone`
<span class="badge badge-success">Public</span>
Activate an account using a pin code received by phone.
Return `404` if the account doesn't exists or if the code is incorrect, the validated account otherwise.
JSON parameters:
@ -224,7 +250,9 @@ JSON parameters:
* `confirmation_key` the PIN code
### `GET /accounts/me/api_key/{auth_token}`
<span class="badge badge-success">Public</span>
Generate and retrieve a fresh API Key from an `auth_token`. The `auth_token` must be attached to an existing account, see [`auth_token` attachement endpoint](#get-accountsauthtokenauthtokenattach) to do so.
Return `404` if the token is invalid or not attached.
@ -232,33 +260,45 @@ Return `404` if the token is invalid or not attached.
This endpoint is also setting the API Key as a Cookie.
### `GET /accounts/me/api_key`
<span class="badge badge-info">User</span>
Generate and retrieve a fresh API Key.
This endpoint is also setting the API Key as a Cookie.
### `GET /accounts/me`
<span class="badge badge-info">User</span>
Retrieve the account information.
### `GET /accounts/me/provision`
<span class="badge badge-info">User</span>
Provision the account by generating a fresh `provisioning_token`.
Return the account object.
### `DELETE /accounts/me`
<span class="badge badge-info">User</span>
Delete the account.
### `POST /accounts/me/email/request`
<span class="badge badge-info">User</span>
Change the account email. An email will be sent to the new email address to confirm the operation.
JSON parameters:
* `email` the new email address, must be unique if `ACCOUNT_EMAIL_UNIQUE` is set to `true`
### `POST /accounts/me/password`
<span class="badge badge-info">User</span>
Change the account password.
JSON parameters:
@ -267,7 +307,9 @@ JSON parameters:
* `password` required, the new password
### `POST /accounts`
<span class="badge badge-warning">Admin</span>
To create an account directly from the API.
If `activated` is set to `false` a random generated `confirmation_key` and `provisioning_token` will be returned to allow further activation using the public endpoints and provision the account. Check `confirmation_key_expires` to also set an expiration date on that `confirmation_key`.
@ -286,7 +328,9 @@ JSON parameters:
* `confirmation_key_expires` optional, a datetime of this format: Y-m-d H:i:s. Only used when `activated` is not used or `false`. Enforces an expiration date on the returned `confirmation_key`. After that datetime public email or phone activation endpoints will return `403`.
### `PUT /accounts/{id}`
<span class="badge badge-warning">Admin</span>
Update an existing account.
JSON parameters:
@ -301,52 +345,74 @@ JSON parameters:
* `dtmf_protocol` optional, values must be `sipinfo`, `sipmessage` or `rfc2833`
### `GET /accounts`
<span class="badge badge-warning">Admin</span>
Retrieve all the accounts, paginated.
### `GET /accounts/{id}`
<span class="badge badge-warning">Admin</span>
Retrieve a specific account.
### `POST /accounts/{id}/recover-by-email`
<span class="badge badge-warning">Admin</span>
Send the account recovery email containing a fresh `provisioning_token` and `confirmation_key`
### `GET /accounts/{sip}/search`
<span class="badge badge-warning">Admin</span>
Search for a specific account by sip address.
### `GET /accounts/{email}/search-by-email`
<span class="badge badge-warning">Admin</span>
Search for a specific account by email.
### `DELETE /accounts/{id}`
<span class="badge badge-warning">Admin</span>
Delete a specific account and its related information.
### `GET /accounts/{id}/activate`
<span class="badge badge-warning">Admin</span>
Activate an account.
### `GET /accounts/{id}/deactivate`
<span class="badge badge-warning">Admin</span>
Deactivate an account.
### `GET /accounts/{id}/provision`
<span class="badge badge-warning">Admin</span>
Provision an account by generating a fresh `provisioning_token`.
## Accounts phone number
### `POST /accounts/me/phone/request`
<span class="badge badge-info">User</span>
Request a specific code by SMS
JSON parameters:
* `phone` the phone number to send the SMS
### `POST /accounts/me/phone`
<span class="badge badge-info">User</span>
Confirm the code received and change the phone number
JSON parameters:
@ -357,35 +423,49 @@ Return the updated account
## Accounts devices
### `GET /accounts/me/devices`
<span class="badge badge-info">User</span>
Return the user registered devices.
### `DELETE /accounts/me/devices/{uuid}`
<span class="badge badge-info">User</span>
Remove one of the user registered devices.
## Accounts contacts
### `GET /accounts/me/contacts`
<span class="badge badge-info">User</span>
Return the user contacts.
### `GET /accounts/me/contacts/{sip}`
<span class="badge badge-info">User</span>
Return a user contact.
## Contacts
### `GET /accounts/{id}/contacts`
<span class="badge badge-warning">Admin</span>
Get all the account contacts.
### `POST /accounts/{id}/contacts/{contact_id}`
<span class="badge badge-warning">Admin</span>
Add a contact to the list.
### `DELETE /accounts/{id}/contacts/{contact_id}`
<span class="badge badge-warning">Admin</span>
Remove a contact from the list.
## Account Actions
@ -393,15 +473,21 @@ Remove a contact from the list.
The following endpoints will return `403 Forbidden` if the requested account doesn't have a DTMF protocol configured.
### `GET /accounts/{id}/actions`
<span class="badge badge-warning">Admin</span>
Show an account related actions.
### `GET /accounts/{id}/actions/{action_id}`
<span class="badge badge-warning">Admin</span>
Show an account related action.
### `POST /accounts/{id}/actions/`
<span class="badge badge-warning">Admin</span>
Create an account action.
JSON parameters:
@ -410,7 +496,9 @@ JSON parameters:
* `code` required, alpha numeric, lowercase
### `PUT /accounts/{id}/actions/{action_id}`
<span class="badge badge-warning">Admin</span>
Create an account action.
JSON parameters:
@ -419,21 +507,29 @@ JSON parameters:
* `code` required, alpha numeric, lowercase
### `DELETE /accounts/{id}/actions/{action_id}`
<span class="badge badge-warning">Admin</span>
Delete an account related action.
## Contacts Lists
### `GET /contacts_lists`
<span class="badge badge-warning">Admin</span>
Show all the contacts lists.
### `GET /contacts_lists/{id}`
<span class="badge badge-warning">Admin</span>
Show a contacts list.
### `POST /contacts_lists`
<span class="badge badge-warning">Admin</span>
Create a contacts list.
JSON parameters:
@ -442,7 +538,9 @@ JSON parameters:
* `description` required
### `PUT /contacts_lists/{id}`
<span class="badge badge-warning">Admin</span>
Update a contacts list.
JSON parameters:
@ -451,37 +549,53 @@ JSON parameters:
* `description` required
### `DELETE /contacts_lists/{id}`
<span class="badge badge-warning">Admin</span>
Delete a contacts list.
### `POST /contacts_lists/{contacts_list_id}/contacts/{contact_id}`
<span class="badge badge-warning">Admin</span>
Add a contact to the contacts list.
### `DELETE /contacts_lists/{contacts_list_id}/contacts/{contact_id}`
<span class="badge badge-warning">Admin</span>
Remove a contact from the contacts list.
### `POST /accounts/{id}/contacts_lists/{contacts_list_id}`
<span class="badge badge-warning">Admin</span>
Add a contacts list to the account.
### `DELETE /accounts/{id}/contacts_lists/{contacts_list_id}`
<span class="badge badge-warning">Admin</span>
Remove a contacts list from the account.
## Account Types
### `GET /account_types`
<span class="badge badge-warning">Admin</span>
Show all the account types.
### `GET /account_types/{id}`
<span class="badge badge-warning">Admin</span>
Show an account type.
### `POST /account_types`
<span class="badge badge-warning">Admin</span>
Create an account type.
JSON parameters:
@ -489,7 +603,9 @@ JSON parameters:
* `key` required, alpha numeric with dashes, lowercase
### `PUT /account_types/{id}`
<span class="badge badge-warning">Admin</span>
Update an account type.
JSON parameters:
@ -497,21 +613,29 @@ JSON parameters:
* `key` required, alpha numeric with dashes, lowercase
### `DELETE /account_types/{id}`
<span class="badge badge-warning">Admin</span>
Delete an account type.
### `POST /accounts/{id}/types/{type_id}`
<span class="badge badge-warning">Admin</span>
Add a type to the account.
### `DELETE /accounts/{id}/contacts/{type_id}`
<span class="badge badge-warning">Admin</span>
Remove a type from the account.
## Messages
### `POST /messages`
<span class="badge badge-warning">Admin</span>
Send a message over SIP.
JSON parameters:
@ -519,6 +643,35 @@ JSON parameters:
* `to` required, SIP address of the receiver
* `body` required, content of the message
## Statistics
FlexiAPI can record logs generated by the FlexiSIP server and compile them into statistics.
### `POST /statistics/messages`
<span class="badge badge-warning">Admin</span>
Announce the creation of a message.
JSON parameters:
* `id` required, string
* `from` required, string the sender of the message
* `sent_at` required, string, format ISO8601, when the mesage was actually sent
* `encrypted` required, boolean
* `conference_id` string
### `PATCH /statistics/messages/{message_id}/to/{to}/devices/{device_id}`
<span class="badge badge-warning">Admin</span>
Complete a message status.
JSON parameters:
* `last_status` required, an integer containing the last status code
* `received_at` required, format ISO8601, when the message was received
# Non-API Endpoints
The following URLs are **not API endpoints** they are not returning `JSON` content and they are not located under `/api` but directly under the root path.
@ -528,11 +681,15 @@ The following URLs are **not API endpoints** they are not returning `JSON` conte
When an account is having an available `provisioning_token` it can be provisioned using the two following URL.
### `GET /provisioning`
<span class="badge badge-success">Public</span>
Return the provisioning information available in the liblinphone configuration file (if correctly configured).
### `GET /provisioning/{provisioning_token}?reset_password`
<span class="badge badge-success">Public</span>
Return the provisioning information available in the liblinphone configuration file.
If the `provisioning_token` is valid the related account information are added to the returned XML. The account is then considered as "provisioned" and those account related information will be removed in the upcoming requests (the content will be the same as the previous url).
@ -543,7 +700,9 @@ URL parameters:
* `reset_password` optional, reset the password while doing the provisioning
### `GET /provisioning/qrcode/{provisioning_token}?reset_password`
<span class="badge badge-success">Public</span>
Return a QRCode that points to the provisioning URL.
URL parameters:
@ -551,13 +710,17 @@ URL parameters:
* `reset_password` optional, reset the password while doing the provisioning
### `GET /provisioning/me`
<span class="badge badge-info">User</span>
Return the same base content as the previous URL and the account related information, similar to the `provisioning_token` endpoint. However this endpoint will always return those information.
## Contacts list
### `GET /contacts/vcard`
<span class="badge badge-info">User</span>
Return the authenticated user contacts list, in [vCard 4.0 format](https://datatracker.ietf.org/doc/html/rfc6350).
Here is the format of the vCard list returned by the endpoint:
@ -582,5 +745,7 @@ END:VCARD
```
### `GET /contacts/vcard/{sip}`
<span class="badge badge-info">User</span>
Return a specific user authenticated contact, in [vCard 4.0 format](https://datatracker.ietf.org/doc/html/rfc6350).