Specyfikacja API – dataquality.pl

[specyfikacja API dla Python – link]  

Zawartość

  • Wprowadzenie
  • Opis komunikacji API
  • Przykładowy nagłówek autoryzacyjny
  • Kody odpowiedzi HTTP
  • Bazowy URL API
  • Lista dostępnych metod API
  • Zadania: Pobieranie listy zadań
  • Zadania: Pobieranie raportu zadania
  • Zadania: Pobieranie statusu zadania
  • Zadania: Pobieranie pliku wynikowego zadania
  • Zadania: Tworzenia nowego zadania
  • Zadania: Usuwanie zadania z kolejki
  • Zadania: Zatrzymanie zadania przetwarzania
  • Konto: Pobieranie informacji o stanie konta
  • Lista obiektów JSON
    • Job
    • Config
    • ConfigInputFormat
    • ConfigInputColumn
    • ConfigExtend
    • JobReport
    • JobReportResults
    • JobReportQualityIssues
    • JobReportQualityNames
    • AccountStatus
    • JobStatus

 

Wprowadzenie

Celem dokumentu jest opisanie poszczególnych metod interfejsu API dostępnego dla klientów dataquality.pl.

Opis komunikacji API

  • Komunikacja z API realizowana jest w oparciu o protokół HTTP
  • API o architekturze RESTful
  • API odpowiada standardowymi kodami HTTP informując o statusie odpowiedzi.
  • Każde zapytanie do API wymaga przesłania tokena autoryzacyjnego
  • Brak załączonego nagłówka z tokenem lub błędny token będzie skutkował odpowiedzią w postaci kodu błędu 401 Nieautoryzowany dostęp
  • API odpowiada w formacie JSON

 

Przykładowy nagłówek autoryzacyjny

Nazwa nagłówka Zawartość nagłówka
Authorization Bearer <TOKEN_AUTORYZACYJNY>

 

Kody odpowiedzi HTTP

API w odpowiedzi na zapytanie zwraca kod HTTP informujący o statusie, oraz ewentualną odpowiedź w postaci łańcucha znaków JSON.
Tabela obsługiwanych kodów HTTP:

Kod HTTP Opis
200 Poprawna odpowiedź
201 Utworzono
202 Zapytanie zaakceptowane, lecz jeszcze nie gotowe
204 Zapytanie wykonane, nie wymaga  odpowiedzi
400 Nieprawidłowe zapytanie lub błąd podczas przetwarzania zapytania
401 Nieautoryzowany dostęp lub błąd autoryzacji
403 Dostęp zabroniony, lub wykonanie akcji niedozwolone
404 Nie znaleziono żądanego obiektu
500 Nieoczekiwany błąd podczas przetwarzania zapytania
501 Metoda nie jest zaimplementowana

 

Bazowy URL API

Wszystkie metody API zawarte w tym dokumencie zaczynają się częścią bazową  /api/v1

Lista dostępnych metod API

Metoda API Opis
GET /jobs Pobieranie listy zadań
GET /jobs/{job_id} Pobieranie raportu zadania
GET /jobs/{job_id}/result Pobieranie pliku wynikowego zadania
GET /jobs/{job_id}/status Pobieranie aktualnego statusu zadania
GET /jobs/{job_id}/report Pobieranie raportu zadania
POST /jobs Tworzenia nowego zadania
DELETE /jobs/{job_id} Usuwanie zadania z kolejki
PUT /jobs/{job_id}/stop Zatrzymanie zadania przetwarzania
GET /account/status Pobieranie informacji o stanie konta

 

Zadania: Pobieranie listy zadań

Zwraca listę zadań użytkownika

Metoda
GET /jobs
Odpowiedź

List<Job> – w odpowiedzi zwraca tablicę obiektów Job

Możliwe statusy HTTP
200 Poprawna odpowiedź
401 Nieautoryzowany dostęp lub błąd autoryzacji
 Przykłady:
HTTP/1.1 200

Content-Type: application/json

 

[{“job_id”:”b7432604-492b-42cc-a45b-cf7eec09b7c1″, “name”:”Nowe zadanie”, “status”:”Nowy”, “start_date”:”23-09-2016 16:22:05″, “end_date”:”23-09-2016 18:12:59″, “source_records”:1,  “processed_records”:100, “price”:100.00}]

 

Zadania: Pobieranie raportu zadania

Zwraca raport zadania

Metoda
GET /jobs/{job_id}
GET /jobs/{job_id}/report
Parametry URL
Parametr Obecność Typ Opis
job_id obowiązkowy String Identyfikator zadania
Odpowiedź

JobReport – w odpowiedzi zwraca obiekt JobReport zawierający dane z pliku raportu przeprocesowanego zadania

Możliwe statusy HTTP
200 Poprawna odpowiedź
202 Żądanie zaakceptowane, lecz raport nie jest gotowy
400 Nieprawidłowe zapytanie lub błąd podczas przetwarzania zapytania
401 Nieautoryzowany dostęp lub błąd autoryzacji
404 Nie znaleziono zadania o podanym identyfikatorze
 Przykłady:
HTTP/1.1 200

Content-Type: application/json

 

{“results”:{“status”:”OK”,”error_description”:””,”input”:1500,”succeed”:1000,”succeed_value”:800,”failed”:500,”level_town”:990,”level_street”:950,”level_building”:800,”level_premises”:500},”quality_issues”:[{“position”:1,”cnt”:350,”total_percent”:70,”reason”:”jakiś powód”},{“position”:2,”cnt”:100,”total_percent”:20,”reason”:”inny powód”},{“position”:3,”cnt”:50,”total_percent”:10,”reason”:”pozostałe powody”}],”quality_names”:{“names_ok”:100,”surnames_ok”:99,”companies_ok”:50,”names_failed”:20,”surnames_failed”:21}}


Zadania: Pobieranie statusu zadania

Zwraca status zadania

Metoda
GET /jobs/{job_id}/status

Parametry URL

Parametr Obecność Typ Opis
job_id obowiązkowy String Identyfikator zadania
Odpowiedź

JobStatus – w odpowiedzi zwraca obiekt JobStatus zawierający informacje o aktualnym statusie zadania

Możliwe statusy HTTP
200 Poprawna odpowiedź
400 Nieprawidłowe zapytanie lub błąd podczas przetwarzania zapytania
401 Nieautoryzowany dostęp lub błąd autoryzacji
404 Nie znaleziono zadania o podanym identyfikatorze
 Przykłady:
HTTP/1.1 200

Content-Type: application/json

 

{“job_id”: “b7432604-492b-42cc-a45b-cf7eec09b7c1″,”status”: “WAITING”}

 

Zadania: Pobieranie pliku wynikowego zadania

Zwraca plik wynikowy zadania CSV

Metoda
GET /jobs/{job_id}/result
Parametry URL
Parametr Obecność Typ Opis
job_id obowiązkowy String Identyfikator zadania
Odpowiedź

W odpowiedzi otrzymujemy plik wynikowy CSV

Możliwe statusy HTTP
200 Poprawna odpowiedź
202 Żądanie zaakceptowane, lecz raport nie jest gotowy
400 Nieprawidłowe zapytanie lub błąd podczas przetwarzania zapytania
401 Nieautoryzowany dostęp lub błąd autoryzacji
404 Nie znaleziono zadania o podanym identyfikatorze
 Przykłady:
HTTP/1.1 200

Content-Type: text/csv

Content-Disposition: attachment; filename=”b7432604-492b-42cc-a45b-cf7eec09b7c1_result.csv”

 

HTTP/1.1 404

Content-Type: application/json

{“code”: 404, “message”: “Zadanie nie zostało znalezione”}

 

HTTP/1.1 400

Content-Type: application/json

{“code”: 400, “errors”: [{“field”: “job_id”, “message”:”Niepoprawny identyfikator zadania”}], “message”: “Niepoprawne zapytanie”}


Zadania: Tworzenia nowego zadania

Tworzy nowe zadanie na podstawie wgrywanego pliku i załączonej konfiguracji

Metoda
POST /jobs
Wymagane Nagłówki zapytania
Content-Type multipart/form-data; boundary={znacznik_graniczny}
Content-Length {rozmiar_zawartości_requestu}
Parametry POST
Parametr Obecność Typ Opis
file obowiązkowy File Plik CSV do przetworzenia
config obowiązkowy String Obiekt JSON Config
Odpowiedź

W odpowiedzi otrzymujemy utworzony obiekt Job

Możliwe statusy HTTP
201 Utworzono
400 Nieprawidłowe zapytanie lub błąd podczas przetwarzania zapytania
401 Nieautoryzowany dostęp lub błąd autoryzacji
Przykłady:
HTTP/1.1 201 Created

Location: http://adresurlapi.pl/jobs/f390eaf6-bade-46e2-bcfd-4695a59445e8

Content-Type: application/json

 

{“job_id”:”b7432604-492b-42cc-a45b-cf7eec09b7c1″, “name”:”Nowe zadanie”, “status”:”Nowy”, “start_date”:”23-09-2016 16:22:05″, “end_date”:”23-09-2016 18:12:59″, “source_records”:1,  “processed_records”:100, “price”:100.00}

 

HTTP/1.1 400

Content-Type: application/json

{“code”: 400, “message”: “Niepoprawny identyfikator zadania”}

 

 

Zadania: Usuwanie zadania z kolejki

Usuwa zadanie z kolejki

Metoda
DELETE /jobs/{job_id}
Parametry URL
Parametr Obecność Typ Opis
job_id obowiązkowy String Identyfikator zadania
Odpowiedź

W odpowiedzi otrzymujemy status 204 potwierdzający poprawne usunięcie zadania

Możliwe statusy HTTP
204 Zapytanie wykonane
400 Nieprawidłowe zapytanie lub błąd podczas przetwarzania zapytania
401 Nieautoryzowany dostęp lub błąd autoryzacji
Przykłady:
HTTP/1.1 204 No Content

 

HTTP/1.1 400

Content-Type: application/json

{“code”: 400, “message”: “Niepoprawny identyfikator zadania”}

 

HTTP/1.1 404

Content-Type: application/json

{“code”: 404, “message”: “Zadanie nie zostało znalezione”}

 

Zadania: Zatrzymanie zadania przetwarzania

Usuwa zadanie z kolejki

Metoda
PUT /jobs/{job_id}/stop
URL Params
Parametr Obecność Typ Opis
job_id obowiązkowy String Identyfikator zadania
Odpowiedź

W odpowiedzi otrzymujemy status 204 potwierdzający poprawne zatrzymanie zadania

Możliwe statusy HTTP
204 Zapytanie wykonane
400 Nieprawidłowe zapytanie lub błąd podczas przetwarzania zapytania
401 Nieautoryzowany dostęp lub błąd autoryzacji
Przykłady:
HTTP/1.1 204 No Content

 

HTTP/1.1 400

Content-Type: application/json

{“code”: 400, “message”: “Niepoprawny identyfikator zadania”}

 

HTTP/1.1 404

Content-Type: application/json

{“code”: 404, “message”: “Zadanie nie zostało znalezione”}


Konto: Pobieranie informacji o stanie konta

Zwraca informacje o koncie użytkownika

Metoda
GET /account/status
Odpowiedź

W odpowiedzi otrzymujemy status obiekt AccountStatus

Możliwe statusy HTTP
200 Poprawna odpowiedź
400 Nieprawidłowe zapytanie lub błąd podczas przetwarzania zapytania
401 Nieautoryzowany dostęp lub błąd autoryzacji
Przykłady:
HTTP/1.1 200 OK

Content-Type: application/json

{“email”: “test2@3e.pl”, “balance”: 1000, “total_records”: 100}

 

HTTP/1.1 400

Content-Type: application/json

{“code”: 400, “message”: “Błąd podczas przetwarzania zapytania”}

 

 Lista obiektów JSON

 

Job

{

“job_id”: “b7432604-492b-42cc-a45b-cf7eec09b7c1”

“name”: “Nowe zadanie”

“status”: “Nowy”

“start_date”: “23-09-2016 16:22:05”

“end_date”: “23-09-2016 18:10:52”

“source_records”: 1000

“processed_records”: 100

“price”: 100.00

}

 

Config

{

“job_name”: “Nazwa zadania”

“input_format”: ConfigInputFormat

“input_columns”: [ConfigInputColumn,ConfigInputColumn]

“extend”: ConfigExtend

}

 

ConfigInputFormat

{

“format”: “csv”,

“field_separator”: “,”,

“text_delimeter”: “”,

“code_page”: “utf-8”,

“header”: 1

}

 

ConfigInputColumn

{

“no”: 0,

“name”: “name”,

“function”: “KOD_POCZTOWY”

}

 

ConfigExtend

{

“teryt”: 0,

“gus”: 0,

“building_info”: 0,

“diagnostic”: 0,

“area_characteristic”: 0

}

 

JobReport

{

“results”: JobReportResults,

“quality_issues”: [JobReportQualityIssues,JobReportQualityIssues,…]

“quality_names”: JobReportQualityNames

}

 

JobReportResults

{

“status”: “OK”

“error_description”: “”

“input”: 0

“succeed”: 1

“succeed_value”: 1

“failed”: 0

“level_town”: 0

“level_street”: 0

“level_building”: 0

“level_premises”: 0

}

 

JobReportQualityIssues

{

“position”: 1

“cnt”: 350

“total_percent”: 70

“reason”: “jakiś powód”

}

 

JobReportQualityNames

{

“names_ok”: 100

“surnames_ok”: 99

“companies_ok”: 50

“names_failed”: 20

“surnames_failed”: 21

}

 

AccountStatus

{

“email”: “test2@3e.pl”

“balance”: 1000

“total_records”: 100

}

 

JobStatus

{

“job_id”: “b7432604-492b-42cc-a45b-cf7eec09b7c1”,

“status”: “WAITING”,

}