Artisans API
Wprowadzenie
Dokumentacja przedstawia listę dostępnych metod oraz wymaganych parametrów. Usługa została stworzona wyłącznie w celach edukacyjnych — do nauki korzystania z REST API (iOS, Android, HTML5) i do ćwiczeń z testowania aplikacji.
Adres bazowy: https://api.artisans.pl. Usługa jest bezpłatna. Metody z grup Kursy walut, Papuga, Biblioteka i Lokalizacja działają bez logowania; pozostałe wymagają tokenu z logowania w nagłówku X-Access-Token.
Dane użytkowników, tokeny i błędy są przechowywane w plikach na serwerze, bez bazy danych. Mogą zostać wyczyszczone po warsztatach.
Format odpowiedzi
Wszystkie odpowiedzi to JSON (application/json; charset=utf-8). Treść żądań POST/PUT wysyłaj jako JSON z nagłówkiem Content-Type: application/json (formularz też jest akceptowany). Daty to znaczniki czasu Unix (sekundy).
Listy mają postać {"data": […], "pagination": {"total", "limit", "offset"}}, a błędy:
{
"error": {
"code": "api.error.token_invalid",
"message": "Token jest niepoprawny lub wygasł."
}
}
Wyjątek: Kursy walut zachowują swój prosty format (tablica / obiekt bez data, błąd jako {"error": "…"}) — korzysta z niego aplikacja Kantor.
Kody odpowiedzi
200 | Sukces — JSON w treści odpowiedzi |
201 | Utworzono zasób (rejestracja, nowy błąd) |
204 | Sukces, pusta odpowiedź (usunięcie, wylogowanie) |
400 | Niepoprawne dane wejściowe — szczegóły w error.message |
401 | Brak tokenu, token niepoprawny albo błędne dane logowania |
404 | Nieistniejący zasób lub ścieżka |
405 | Metoda HTTP nieobsługiwana przez tę ścieżkę |
Kursy walut ¶
Lista kursów ¶
Kursy walut względem PLN dla aplikacji Kantor. Dane są stałe, więc wyniki w aplikacji i w testach są zawsze takie same. Bez autoryzacji.
Kursy są stringami ("4.2850", nie 4.285) — celowo. Liczba JSON trafiłaby do aplikacji przez Double i mogłaby stać się 4.284999…. Pieniądze zamieniamy na Decimal sami, zawsze z kropką jako separatorem.
Swift — pobranie kursów
struct Rate: Decodable {
let code: String // "EUR"
let name: String // "euro"
let buy: String // "4.2850"
let sell: String // "4.3150"
}
let url = URL(string: "https://api.artisans.pl/rates")!
let (data, _) = try await URLSession.shared.data(from: url)
let rates = try JSONDecoder().decode([Rate].self, from: data)| Kod | Waluta | Kupno | Sprzedaż | Średni |
|---|---|---|---|---|
EUR | euro | 4.2850 | 4.3150 | 4.3012 |
USD | dolar amerykański | 3.9120 | 3.9480 | 3.9301 |
GBP | funt szterling | 5.0810 | 5.1290 | 5.1048 |
CHF | frank szwajcarski | 4.4520 | 4.4960 | 4.4737 |
JPY | jen (100) | 2.5710 | 2.6030 | 2.5869 |
CZK | korona czeska | 0.1702 | 0.1726 | 0.1714 |
NOK | korona norweska | 0.3631 | 0.3679 | 0.3655 |
SEK | korona szwedzka | 0.3702 | 0.3748 | 0.3725 |
DKK | korona duńska | 0.5741 | 0.5797 | 0.5769 |
HUF | forint (100) | 1.0912 | 1.1048 | 1.0980 |
CAD | dolar kanadyjski | 2.8040 | 2.8320 | 2.8178 |
AUD | dolar australijski | 2.5530 | 2.5810 | 2.5669 |
Wszystkie kursyGET/rates
Kod waluty, nazwa, kurs kupna i sprzedaży w PLN.
Example URI
200Headers
Content-Type: application/json; charset=utf-8Body
[
{
"code": "EUR",
"name": "euro",
"buy": "4.2850",
"sell": "4.3150"
},
{
"code": "USD",
"name": "dolar amerykański",
"buy": "3.9120",
"sell": "3.9480"
}
… i kolejne waluty
]Kurs waluty ¶
Kurs średniGET/rates/{code}
Example URI
- code
string(required) Example: EURKod waluty ISO 4217. Wielkość liter nie ma znaczenia (
eur=EUR).
200Headers
Content-Type: application/json; charset=utf-8Body
{
"base": "EUR",
"quote": "PLN",
"rate": "4.3012"
}404Headers
Content-Type: application/json; charset=utf-8Body
{
"error": "Unknown currency: XXX"
}Autoryzacja ¶
Rejestracja ¶
Rejestracja nie wymaga potwierdzenia adresu email. Hasło musi mieć co najmniej 8 znaków.
RejestracjaPOST/auth/register
Example URI
Headers
Content-Type: application/jsonBody
{
"email": "adres@example.com",
"password": "minimum-8-characters"
}201Headers
Content-Type: application/json; charset=utf-8Body
{
"success": {
"message": "User created successfully",
"key": "api.auth.info.user_created"
}
}400Headers
Content-Type: application/json; charset=utf-8Body
{
"error": {
"code": "api.error.email_taken",
"message": "Ten adres email jest już zarejestrowany."
}
}Logowanie ¶
Po rejestracji należy się zalogować, aby otrzymać token sesji (80 znaków, ważny 1 rok).
LogowaniePOST/auth/login
Example URI
Headers
Content-Type: application/jsonBody
{
"email": "adres@example.com",
"password": "minimum-8-characters"
}200Headers
Content-Type: application/json; charset=utf-8Body
{
"data": {
"token": "YOUR_80_CHARACTERS_SESSION_TOKEN_STRING"
}
}401Headers
Content-Type: application/json; charset=utf-8Body
{
"error": {
"code": "api.error.invalid_credentials",
"message": "Niepoprawny email lub hasło."
}
}Token uwierzytelnienia ¶
Token jest wymagany przez metody z grup Autoryzacja → Token, Mój profil i Administracja. Przesyłaj go w nagłówku X-Access-Token (albo jako parametr ?token=).
Lista sesjiGET/auth/tokens
Example URI
Headers
X-Access-Token: YOUR_80_CHARACTERS_SESSION_TOKEN_STRING200Headers
Content-Type: application/json; charset=utf-8Body
{
"data": [
{
"token": "YOUR_80_CHARACTERS_SESSION_TOKEN_STRING",
"agent": "Kantor/1.0 CFNetwork/3826 Darwin/25.0.0",
"created_at": 1763459400,
"expire_at": 1794995400,
"last_request_at": 1763459520
}
]
}401Headers
Content-Type: application/json; charset=utf-8Body
{
"error": {
"code": "api.error.token_invalid",
"message": "Token jest niepoprawny lub wygasł."
}
}WylogowanieDELETE/auth/tokens
Unieważnia token przesłany w żądaniu.
Example URI
Headers
X-Access-Token: YOUR_80_CHARACTERS_SESSION_TOKEN_STRING204Mój profil ¶
Mój profil ¶
Podstawowe daneGET/profile
Example URI
Headers
X-Access-Token: YOUR_80_CHARACTERS_SESSION_TOKEN_STRING200Headers
Content-Type: application/json; charset=utf-8Body
{
"data": {
"id": "fbe06463-84be-4b1e-a4c3-8717a9e799ab",
"avatar": "https://api.artisans.pl/avatars/fbe06463-84be-4b1e-a4c3-8717a9e799ab-1763459400.jpg",
"firstname": "John",
"lastname": "Doe",
"email": "john.doe@example.com",
"created_at": 1763459400,
"updated_at": 1763459400
}
}401Headers
Content-Type: application/json; charset=utf-8Body
{
"error": {
"code": "api.error.token_invalid",
"message": "Token jest niepoprawny lub wygasł."
}
}Aktualizacja danychPUT/profile
Wszystkie pola są opcjonalne — zmieniane są tylko przesłane: firstname, lastname, email.
Example URI
Headers
X-Access-Token: YOUR_80_CHARACTERS_SESSION_TOKEN_STRING
Content-Type: application/jsonBody
{
"firstname": "John",
"lastname": "Doe"
}200Headers
Content-Type: application/json; charset=utf-8Body
{
"data": {
"id": "fbe06463-84be-4b1e-a4c3-8717a9e799ab",
"avatar": null,
"firstname": "John",
"lastname": "Doe",
"email": "john.doe@example.com",
"created_at": 1763459400,
"updated_at": 1763459460
}
}400Headers
Content-Type: application/json; charset=utf-8Body
{
"error": {
"code": "error.validation",
"message": "Niepoprawny adres email."
}
}Avatar ¶
Obraz JPG, PNG, GIF lub WEBP, maks. 1 MB. Wyślij go jako pole avatar w multipart/form-data albo bezpośrednio jako treść żądania.
Uaktualnij avatarPOST/avatar
Example URI
Headers
X-Access-Token: YOUR_80_CHARACTERS_SESSION_TOKEN_STRING
Content-Type: image/jpegBody
<binarne dane obrazu>200Headers
Content-Type: application/json; charset=utf-8Body
{
"data": {
"avatar": "https://api.artisans.pl/avatars/fbe06463-84be-4b1e-a4c3-8717a9e799ab-1763459400.jpg"
}
}400Headers
Content-Type: application/json; charset=utf-8Body
{
"error": {
"code": "api.error.avatar_size_too_big",
"message": "Rozmiar avatara jest za duży (maks. 1 MB)."
}
}Usunięcie avataraDELETE/avatar
Example URI
Headers
X-Access-Token: YOUR_80_CHARACTERS_SESSION_TOKEN_STRING204Papuga ¶
Papuga zwraca wszystko, co odebrał serwer: metodę, nagłówki oraz parametry z adresu i treści żądania (JSON albo formularz). Bez autoryzacji — idealna do sprawdzania, co naprawdę wysyła aplikacja.
Dostępne metody ¶
GETGET/parrot{?sample_key_1,sample_key_2}
Example URI
- sample_key_1
string(optional) Example: value_1Dowolny parametr — zostanie odesłany w
data.- sample_key_2
string(optional) Example: value_2Dowolny parametr.
200Headers
Content-Type: application/json; charset=utf-8Body
{
"method": "GET",
"headers": {
"accept": "*/*",
"host": "api.artisans.pl",
"user-agent": "curl/8.7.1"
},
"data": {
"sample_key_1": "value_1",
"sample_key_2": "value_2"
}
}POSTPOST/parrot{?sample_key_1,sample_key_2}
Example URI
- sample_key_1
string(optional) Example: value_1Dowolny parametr — zostanie odesłany w
data.- sample_key_2
string(optional) Example: value_2Dowolny parametr.
Headers
Content-Type: application/jsonBody
{
"sample_key_1": "value_1",
"sample_key_2": "value_2"
}200Headers
Content-Type: application/json; charset=utf-8Body
{
"method": "POST",
"headers": {
"content-type": "application/json",
"host": "api.artisans.pl"
},
"data": {
"sample_key_1": "value_1",
"sample_key_2": "value_2"
}
}PUTPUT/parrot{?sample_key_1,sample_key_2}
Example URI
- sample_key_1
string(optional) Example: value_1Dowolny parametr — zostanie odesłany w
data.- sample_key_2
string(optional) Example: value_2Dowolny parametr.
Headers
Content-Type: application/jsonBody
{
"sample_key_1": "value_1"
}200Headers
Content-Type: application/json; charset=utf-8Body
{
"method": "PUT",
"headers": {
"content-type": "application/json",
"host": "api.artisans.pl"
},
"data": {
"sample_key_1": "value_1"
}
}DELETEDELETE/parrot{?sample_key_1,sample_key_2}
Example URI
- sample_key_1
string(optional) Example: value_1Dowolny parametr — zostanie odesłany w
data.- sample_key_2
string(optional) Example: value_2Dowolny parametr.
204Administracja ¶
Prosty bug tracker. Każdy użytkownik widzi wyłącznie swoje błędy — wymagany token.
Lista projektów ¶
Namespace to skrót (np. od nazwy projektu), 2–10 liter lub cyfr, zawsze zwracany dużymi literami. Lista powstaje z namespace’ów Twoich błędów.
PobierzGET/bugs/namespaces
Example URI
Headers
X-Access-Token: YOUR_80_CHARACTERS_SESSION_TOKEN_STRING200Headers
Content-Type: application/json; charset=utf-8Body
{
"data": [
{
"namespace": "KRK"
},
{
"namespace": "WAW"
}
],
"pagination": {
"total": 2,
"limit": 10,
"offset": 0
}
}401Headers
Content-Type: application/json; charset=utf-8Body
{
"error": {
"code": "api.error.token_invalid",
"message": "Token jest niepoprawny lub wygasł."
}
}Lista błędów ¶
PobierzGET/bugs{?namespace,status,limit,offset}
Sortowanie: od najwyższego priority.
Example URI
- namespace
string(optional) Example: KRKSkrócona nazwa projektu. Pominięty — zwracane są wszystkie błędy.
- status
string(optional)open,in_progressalboclosed.- limit
number(optional)Liczba rekordów na stronie, 1–100. Domyślnie
10.- offset
number(optional)Ile rekordów pominąć. Domyślnie
0.
Headers
X-Access-Token: YOUR_80_CHARACTERS_SESSION_TOKEN_STRING200Headers
Content-Type: application/json; charset=utf-8Body
{
"data": [
{
"id": "1001",
"content": "Przycisk „Zaloguj” nie reaguje na iPhone SE.",
"priority": 0.85,
"status": "open",
"namespace": "KRK",
"created_at": 1763459400,
"updated_at": 1763459400
}
],
"pagination": {
"total": 1,
"limit": 10,
"offset": 0
}
}401Headers
Content-Type: application/json; charset=utf-8Body
{
"error": {
"code": "api.error.token_invalid",
"message": "Token jest niepoprawny lub wygasł."
}
}DodajPOST/bugs{?namespace,status,limit,offset}
Wymagane: content. Opcjonalne: priority (0–1, domyślnie 0.5), status (domyślnie open), namespace.
Example URI
- namespace
string(optional) Example: KRKSkrócona nazwa projektu. Pominięty — zwracane są wszystkie błędy.
- status
string(optional)open,in_progressalboclosed.- limit
number(optional)Liczba rekordów na stronie, 1–100. Domyślnie
10.- offset
number(optional)Ile rekordów pominąć. Domyślnie
0.
Headers
X-Access-Token: YOUR_80_CHARACTERS_SESSION_TOKEN_STRING
Content-Type: application/jsonBody
{
"content": "Przycisk „Zaloguj” nie reaguje na iPhone SE.",
"priority": 0.85,
"namespace": "KRK"
}201Headers
Location: /bugs/1001
Content-Type: application/json; charset=utf-8Body
{
"data": {
"id": "1001",
"content": "Przycisk „Zaloguj” nie reaguje na iPhone SE.",
"priority": 0.85,
"status": "open",
"namespace": "KRK",
"created_at": 1763459400,
"updated_at": 1763459400
}
}400Headers
Content-Type: application/json; charset=utf-8Body
{
"error": {
"code": "error.validation",
"message": "Pole content jest wymagane."
}
}Błąd ¶
PobierzGET/bugs/{id}
Example URI
- id
string(required) Example: 1001Identyfikator błędu.
Headers
X-Access-Token: YOUR_80_CHARACTERS_SESSION_TOKEN_STRING200Headers
Content-Type: application/json; charset=utf-8Body
{
"data": {
"id": "1001",
"content": "Przycisk „Zaloguj” nie reaguje na iPhone SE.",
"priority": 0.85,
"status": "open",
"namespace": "KRK",
"created_at": 1763459400,
"updated_at": 1763459400
}
}404Headers
Content-Type: application/json; charset=utf-8Body
{
"error": {
"code": "api.error.bug_not_found",
"message": "Nie znaleziono błędu o id 1001."
}
}UaktualnijPUT/bugs/{id}
Zmieniane są tylko przesłane pola.
Example URI
- id
string(required) Example: 1001Identyfikator błędu.
Headers
X-Access-Token: YOUR_80_CHARACTERS_SESSION_TOKEN_STRING
Content-Type: application/jsonBody
{
"priority": 0.3,
"status": "closed"
}200Headers
Content-Type: application/json; charset=utf-8Body
{
"data": {
"priority": 0.3,
"status": "closed",
"updated_at": 1763463000,
"id": "1001",
"content": "Przycisk „Zaloguj” nie reaguje na iPhone SE.",
"namespace": "KRK",
"created_at": 1763459400
}
}UsuńDELETE/bugs/{id}
Example URI
- id
string(required) Example: 1001Identyfikator błędu.
Headers
X-Access-Token: YOUR_80_CHARACTERS_SESSION_TOKEN_STRING204Biblioteka ¶
Lista książek ¶
Pobierz listęGET/books{?q,limit,offset}
Example URI
- q
string(optional)Szukaj w tytule i autorze.
- limit
number(optional)Liczba rekordów na stronie, 1–100. Domyślnie
20.- offset
number(optional)Ile rekordów pominąć. Domyślnie
0.
200Headers
Content-Type: application/json; charset=utf-8Body
{
"data": [
{
"id": "dbc173e55fad441bb15195d16954f05c",
"isbn": "978-83-240-2247-2",
"title": "Alibi na szczęście. Cz. 1",
"author": "Anna Ficner-Ogonowska",
"cover": "https://d11570mjfj6i5h.cloudfront.net/books/1b6453892473a467d07372d45eb05abc2031647a.jpg",
"publisher": "Społeczny Instytut Wydawniczy Znak",
"year": 2012
}
],
"pagination": {
"total": 414,
"limit": 20,
"offset": 0
}
}Książka ¶
PobierzGET/books/{id}
Example URI
- id
string(required) Example: dbc173e55fad441bb15195d16954f05cIdentyfikator książki (32 znaki).
200Headers
Content-Type: application/json; charset=utf-8Body
{
"data": {
"id": "dbc173e55fad441bb15195d16954f05c",
"isbn": "978-83-240-2247-2",
"title": "Alibi na szczęście. Cz. 1",
"author": "Anna Ficner-Ogonowska",
"cover": "https://d11570mjfj6i5h.cloudfront.net/books/1b6453892473a467d07372d45eb05abc2031647a.jpg",
"publisher": "Społeczny Instytut Wydawniczy Znak",
"year": 2012
}
}404Headers
Content-Type: application/json; charset=utf-8Body
{
"error": {
"code": "api.error.book_not_found",
"message": "Nie znaleziono książki."
}
}Lokalizacja ¶
Państwa ¶
Lista państwGET/countries
Obiekt: dwuliterowy kod ISO 3166-1 → polska nazwa, posortowany po nazwie.
Example URI
200Headers
Content-Type: application/json; charset=utf-8Body
{
"data": {
"af": "Afganistan",
"al": "Albania",
…
"pl": "Polska",
…
"gb": "Wielka Brytania"
}
}Lista miast ¶
Miasta z bazy GeoNames (ok. 24 tys. — powyżej 15 tys. mieszkańców oraz stolice regionów), posortowane od największego.
Pobierz listęGET/cities{?country_code,limit,offset}
Example URI
- country_code
string(optional) Example: plDwuliterowy kod państwa ISO 3166-1, np.
us,de,fr,nl,pl.- limit
number(optional)Liczba rekordów na stronie, 1–100. Domyślnie
10.- offset
number(optional)Ile rekordów pominąć. Domyślnie
0.
200Headers
Content-Type: application/json; charset=utf-8Body
{
"data": [
{
"geonameid": "756135",
"name": "Warsaw",
"asciiname": "Warsaw",
"lat": 52.22977,
"lon": 21.01178,
"feature_code": "PPLC",
"population": 1702139,
"country_code": "pl"
},
{
"geonameid": "3093133",
"name": "Łódź",
"asciiname": "Lodz",
"lat": 51.75,
"lon": 19.46667,
"feature_code": "PPLA",
"population": 768755,
"country_code": "pl"
}
],
"pagination": {
"total": 329,
"limit": 10,
"offset": 0
}
}400Headers
Content-Type: application/json; charset=utf-8Body
{
"error": {
"code": "api.error.invalid_country_code",
"message": "Parametr country_code musi mieć 2 litery (ISO 3166-1)."
}
}