Przejdź do treści

Wstęp

W tym miejscu opisano funkcje interfejsu API VoIPstudio, które zapewniają dostęp do wszystkich podstawowych zasobów VoIPstudio.

Ogólne

REST API umożliwia klientom VoIPstudio dostęp do szerokiej gamy zasobów. Nasze API ma przewidywalne, zorientowane na zasoby adresy URL i używa kodów odpowiedzi HTTP do wskazywania błędów API. Używamy wbudowanych funkcji HTTP, takich jak uwierzytelnianie HTTP i czasowniki HTTP, które są zrozumiałe dla zwykłych klientów HTTP. Obsługujemy udostępnianie zasobów między źródłami, umożliwiając bezpieczną interakcję z naszym interfejsem API z poziomu aplikacji internetowej po stronie klienta. JSON jest zwracany przez wszystkie odpowiedzi API, w tym błędy.

Punkty końcowe

Podstawowy URL dla API id:

https://l7api.com/v1.1/voipstudio/

Poświadczenie

Aby zapewnić bezpieczną komunikację, możesz utworzyć klucz API, który będzie używany do autoryzacji interfejsu API

Komunikacja między aplikacjami klienta a interfejsem API VoIPstudio jest zabezpieczona przez podstawowe uwierzytelnianie HTTP przez SSL.

Przed wysłaniem żądań do API musisz najpierw zalogować się przy użyciu adresu e-mail i hasła lub utworzyć klucz API, który będzie używany do autoryzacji. Po pomyślnym uwierzytelnieniu API zwróci unikalne atrybuty user_id i user_token, których należy użyć do zalogowania.

E-mail i hasło

Żądanie logowania przy użyciu adresu e-mail i hasła:

  curl -H "Content-Type: application/json" -X POST -d '{"email":"jsmith@example.com","password":"$ecretPas$$"}' https://l7api.com/v1.1/voipstudio/login

Przykład żądania HTTP:

POST /v1.1/voipstudio/login HTTP/1.1
User-Agent: curl/7.26.0
Host: l7api.com
Accept: */*
Content-Type: application/json
Content-Length: 55
Connection: close
{"email":"jsmith@example.com","password":"$ecretPas$$"}

Przykład pomyślnej odpowiedzi:

  {
"message":"Login success",
"user_token":"8e9bc12575e639c993ba5dd8a0e7ce2250211b9a",
"user_id":123456
}

Klucz REST API

Wykonaj poniższe czynności, aby dodać klucz API dla użytkownika. Po utworzeniu trwałego klucza API nie ma potrzeby każdorazowego logowania się za pomocą adresu e-mail / hasła.

  1. Przejdź do panelu administracyjnego.
  2. Otwórz sekcję użytkownicy 1.
  3. Kliknij, na użytkownika.
  4. Przejdź do opcji Klucze API 2.
  5. Wpisz nazwę klucza API 3. Na przykład nazwa aplikacji, która będzie używać tego klucza API.
  6. kliknij przycisk Dodaj 4.
  7. Kliknij ikonę Klucza 6 i wybierz Pokaż szczegóły, aby wyświetlić rzeczywisty wygenerowany „Klucz API”.

rest-api-keys.png

Figure 1.1 Add API Key.

Tworzenie żądań HTTP

Uwierzytelnianie w interfejsie API odbywa się za pośrednictwem podstawowego uwierzytelniania HTTP. Ten typ uwierzytelniania powinien być prostą operacją w większości popularnych języków programowania. Oczekuje się, że przychodzące żądania obsługiwane przez nasz interfejs API będą miały nagłówek Authorization z wartością zakodowaną w formacie base64 utworzoną na podstawie user_id i user_token zwróconych z pomyślnej odpowiedzi login lub user_id i utworzonego API Key. Aby uzyskać wartość base64 dla Authorization, Base64 koduje swoje user_id i user_token oddzielone dwukropkiem.

Oczekiwany jest nagłówek Authorization w następującym formacie:

Authorization: Basic base64('user_id:user_token')

lub

Authorization: Basic base64('user_id:API_Key')

Przykład uwierzytelnionego żądania:

używając user_token zwróconego przez POST /login

curl -H "Content-Type: application/json" -H "Authorization: Basic base64('user_id:user_token')"  https://l7api.com/v1.1/voipstudio/cdrs

lub używając API_Key

curl -H "Content-Type: application/json" -H "Authorization: Basic base64('user_id:API_Key')"  https://l7api.com/v1.1/voipstudio/cdrs

lub skróconej formy z parametrem curl -u, --user `:

curl -u user_id:user_token -H "Content-Type: application/json" https://l7api.com/v1.1/voipstudio/cdrs

lub używając API_Key

curl -u user_id:API_Key -H "Content-Type: application/json" https://l7api.com/v1.1/voipstudio/cdrs

Odpowiedzi HTTP

VoIPstudio REST API używa konwencjonalnych kodów odpowiedzi HTTP do wskazania powodzenia lub niepowodzenia żądania API. Ogólnie, kody z zakresu 2xx wskazują na sukces, kody z zakresu 4xx wskazują błąd, który nie powiódł się, biorąc pod uwagę podane informacje (np. Pominięto wymagany parametr itp.), A kody z zakresu 5xx wskazują błąd serwera.

Każda pomyślna odpowiedź, w zależności od metody HTTP, zawiera następujące właściwości:

  • GET collection of resources:

    • data - an array of resources data
    • total - total number of resources
  • GET single resource:

    • data - resources data
    • links - links to related resources

Każda odpowiedź błędu zawiera następujące właściwości:

* `message` - general error message
* `errors` - an array of error messages

Pager

W przypadku punktów końcowych gromadzenia danych, takich jak GET https://l7api.com/v1.1/voipstudio/cdrs można użyć pagera do zwrócenia określonej liczby rekordów z danej strony w zestawie danych. Aby zastosować pager, dołącz następujące parametry do adresu URL ?page=N&limit=Z gdzie N to numer strony, a Z to liczba rekordów do zwrócenia (maksymalnie 5000).

Filtry

Aby filtrować dane, parametr filter można przekazać jako ciąg zapytania z adresem URL. Wartość parametru „filter” musi być ciągiem zakodowanym w formacie JSON w formacie pokazanym poniżej:

[
{"property":"_PROPERTY_NAME_","operator":"_OPERATOR_","value":"_SEARCH_VALUE_"},
{"property":"_PROPERTY_NAME_","operator":"_OPERATOR_","value":"_SEARCH_VALUE_"}
...
]

Trzy powyższe tokeny _PROPERTY_NAME_, _OPERATOR_ oraz _VALUE_TO_SEARCH_ powinny być interpretowane jak poniżej:

  • _PROPERTY_NAME_ może to być dowolna właściwość należąca do określonego obiektu punktu końcowego. Zobacz sekcję Zasoby poniżej, aby uzyskać szczegółowe wyjaśnienie modelu danych dla każdego punktu końcowego.

  • _OPERATOR_ może być jednym z:

    • eq lub = podczas wyszukiwania rekordów z wartością property równą _SEARCH_VALUE_
    • ne, neq, <> lub != podczas wyszukiwania rekordów z wartością property, która NIE równa się z _SEARCH_VALUE_
    • lt lub < podczas wyszukiwania rekordów o wartości property mniejszej niż _SEARCH_VALUE_
    • lte lub <= podczas wyszukiwania rekordów o wartości property mniejszej lub równej niż _SEARCH_VALUE_
    • gt lub > podczas wyszukiwania rekordów z wartością property większą niż _SEARCH_VALUE_
    • gte lub >= podczas wyszukiwania rekordów z wartością property większą lub równą _SEARCH_VALUE_
    • in podczas wyszukiwania rekordów z wartością property uwzględnioną w _SEARCH_VALUE_ (Uwaga: wartość wyszukiwania należy przekazać jako tablicę, np .: [ "foo", "bar" ])
    • like podczas wyszukiwania rekordów z wartością property pasującą do wzorca _SEARCH_VALUE_
    • notlike podczas wyszukiwania rekordów z wartością property NIE pasującą do wzorca z _SEARCH_VALUE_
  • _SEARCH_VALUE_ wartość, którą chcesz wyszukać

Przykład żądania do punktu końcowego / cdrs wyszukującego połączenia przychodzące (właściwośćdst_id równa się identyfikatorowi użytkownika) do identyfikatora użytkownika 123456 po 1 września 2018 r .:

curl -u user_id:API_Key -H "Content-Type: application/json"
https://l7api.com/v1.1/voipstudio/cdrs?filter=[
{"property":"dst_id","operator":"eq","value":"123456"},
{"property":"calldate","operator":"gt","value":"2018-09-01 00:00:00"}
]

Grupowanie

Parametr group_by jest dostępny do grupowania rekordów według określonej właściwości: `GET https://l7api.com/v1.1/voipstudio/cdrs?group_by=src. Ten parametr należy przekazać jako ciąg zapytania URL.