Back to top

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

200Sukces — JSON w treści odpowiedzi
201Utworzono zasób (rejestracja, nowy błąd)
204Sukces, pusta odpowiedź (usunięcie, wylogowanie)
400Niepoprawne dane wejściowe — szczegóły w error.message
401Brak tokenu, token niepoprawny albo błędne dane logowania
404Nieistniejący zasób lub ścieżka
405Metoda 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)
KodWalutaKupnoSprzedażŚredni
EUReuro4.28504.31504.3012
USDdolar amerykański3.91203.94803.9301
GBPfunt szterling5.08105.12905.1048
CHFfrank szwajcarski4.45204.49604.4737
JPYjen (100)2.57102.60302.5869
CZKkorona czeska0.17020.17260.1714
NOKkorona norweska0.36310.36790.3655
SEKkorona szwedzka0.37020.37480.3725
DKKkorona duńska0.57410.57970.5769
HUFforint (100)1.09121.10481.0980
CADdolar kanadyjski2.80402.83202.8178
AUDdolar australijski2.55302.58102.5669

Wszystkie kursy
GET/rates

Kod waluty, nazwa, kurs kupna i sprzedaży w PLN.

Example URI

GET https://api.artisans.pl/rates
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
[
 {
  "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 średni
GET/rates/{code}

Example URI

GET https://api.artisans.pl/rates/EUR
URI Parameters
HideShow
code
string (required) Example: EUR

Kod waluty ISO 4217. Wielkość liter nie ma znaczenia (eur = EUR).

Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "base": "EUR",
  "quote": "PLN",
  "rate": "4.3012"
}
Response  404
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "error": "Unknown currency: XXX"
}

Autoryzacja

Rejestracja

Rejestracja nie wymaga potwierdzenia adresu email. Hasło musi mieć co najmniej 8 znaków.

Rejestracja
POST/auth/register

Example URI

POST https://api.artisans.pl/auth/register
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "email": "adres@example.com",
  "password": "minimum-8-characters"
}
Response  201
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "success": {
    "message": "User created successfully",
    "key": "api.auth.info.user_created"
  }
}
Response  400
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "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).

Logowanie
POST/auth/login

Example URI

POST https://api.artisans.pl/auth/login
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "email": "adres@example.com",
  "password": "minimum-8-characters"
}
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "data": {
    "token": "YOUR_80_CHARACTERS_SESSION_TOKEN_STRING"
  }
}
Response  401
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "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 sesji
GET/auth/tokens

Example URI

GET https://api.artisans.pl/auth/tokens
Request
HideShow
Headers
X-Access-Token: YOUR_80_CHARACTERS_SESSION_TOKEN_STRING
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "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
    }
  ]
}
Response  401
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "error": {
    "code": "api.error.token_invalid",
    "message": "Token jest niepoprawny lub wygasł."
  }
}

Wylogowanie
DELETE/auth/tokens

Unieważnia token przesłany w żądaniu.

Example URI

DELETE https://api.artisans.pl/auth/tokens
Request
HideShow
Headers
X-Access-Token: YOUR_80_CHARACTERS_SESSION_TOKEN_STRING
Response  204

Mój profil

Mój profil

Podstawowe dane
GET/profile

Example URI

GET https://api.artisans.pl/profile
Request
HideShow
Headers
X-Access-Token: YOUR_80_CHARACTERS_SESSION_TOKEN_STRING
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "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
  }
}
Response  401
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "error": {
    "code": "api.error.token_invalid",
    "message": "Token jest niepoprawny lub wygasł."
  }
}

Aktualizacja danych
PUT/profile

Wszystkie pola są opcjonalne — zmieniane są tylko przesłane: firstname, lastname, email.

Example URI

PUT https://api.artisans.pl/profile
Request
HideShow
Headers
X-Access-Token: YOUR_80_CHARACTERS_SESSION_TOKEN_STRING
Content-Type: application/json
Body
{
  "firstname": "John",
  "lastname": "Doe"
}
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "data": {
    "id": "fbe06463-84be-4b1e-a4c3-8717a9e799ab",
    "avatar": null,
    "firstname": "John",
    "lastname": "Doe",
    "email": "john.doe@example.com",
    "created_at": 1763459400,
    "updated_at": 1763459460
  }
}
Response  400
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "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 avatar
POST/avatar

Example URI

POST https://api.artisans.pl/avatar
Request
HideShow
Headers
X-Access-Token: YOUR_80_CHARACTERS_SESSION_TOKEN_STRING
Content-Type: image/jpeg
Body
<binarne dane obrazu>
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "data": {
    "avatar": "https://api.artisans.pl/avatars/fbe06463-84be-4b1e-a4c3-8717a9e799ab-1763459400.jpg"
  }
}
Response  400
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "error": {
    "code": "api.error.avatar_size_too_big",
    "message": "Rozmiar avatara jest za duży (maks. 1 MB)."
  }
}

Usunięcie avatara
DELETE/avatar

Example URI

DELETE https://api.artisans.pl/avatar
Request
HideShow
Headers
X-Access-Token: YOUR_80_CHARACTERS_SESSION_TOKEN_STRING
Response  204

Papuga

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

GET
GET/parrot{?sample_key_1,sample_key_2}

Example URI

GET https://api.artisans.pl/parrot?sample_key_1=value_1&sample_key_2=value_2
URI Parameters
HideShow
sample_key_1
string (optional) Example: value_1

Dowolny parametr — zostanie odesłany w data.

sample_key_2
string (optional) Example: value_2

Dowolny parametr.

Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "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"
  }
}

POST
POST/parrot{?sample_key_1,sample_key_2}

Example URI

POST https://api.artisans.pl/parrot?sample_key_1=value_1&sample_key_2=value_2
URI Parameters
HideShow
sample_key_1
string (optional) Example: value_1

Dowolny parametr — zostanie odesłany w data.

sample_key_2
string (optional) Example: value_2

Dowolny parametr.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "sample_key_1": "value_1",
  "sample_key_2": "value_2"
}
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "method": "POST",
  "headers": {
    "content-type": "application/json",
    "host": "api.artisans.pl"
  },
  "data": {
    "sample_key_1": "value_1",
    "sample_key_2": "value_2"
  }
}

PUT
PUT/parrot{?sample_key_1,sample_key_2}

Example URI

PUT https://api.artisans.pl/parrot?sample_key_1=value_1&sample_key_2=value_2
URI Parameters
HideShow
sample_key_1
string (optional) Example: value_1

Dowolny parametr — zostanie odesłany w data.

sample_key_2
string (optional) Example: value_2

Dowolny parametr.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "sample_key_1": "value_1"
}
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "method": "PUT",
  "headers": {
    "content-type": "application/json",
    "host": "api.artisans.pl"
  },
  "data": {
    "sample_key_1": "value_1"
  }
}

DELETE
DELETE/parrot{?sample_key_1,sample_key_2}

Example URI

DELETE https://api.artisans.pl/parrot?sample_key_1=value_1&sample_key_2=value_2
URI Parameters
HideShow
sample_key_1
string (optional) Example: value_1

Dowolny parametr — zostanie odesłany w data.

sample_key_2
string (optional) Example: value_2

Dowolny parametr.

Response  204

Administracja

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.

Pobierz
GET/bugs/namespaces

Example URI

GET https://api.artisans.pl/bugs/namespaces
Request
HideShow
Headers
X-Access-Token: YOUR_80_CHARACTERS_SESSION_TOKEN_STRING
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "data": [
    {
      "namespace": "KRK"
    },
    {
      "namespace": "WAW"
    }
  ],
  "pagination": {
    "total": 2,
    "limit": 10,
    "offset": 0
  }
}
Response  401
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "error": {
    "code": "api.error.token_invalid",
    "message": "Token jest niepoprawny lub wygasł."
  }
}

Lista błędów

Pobierz
GET/bugs{?namespace,status,limit,offset}

Sortowanie: od najwyższego priority.

Example URI

GET https://api.artisans.pl/bugs?namespace=KRK
URI Parameters
HideShow
namespace
string (optional) Example: KRK

Skrócona nazwa projektu. Pominięty — zwracane są wszystkie błędy.

status
string (optional) 

open, in_progress albo closed.

limit
number (optional) 

Liczba rekordów na stronie, 1–100. Domyślnie 10.

offset
number (optional) 

Ile rekordów pominąć. Domyślnie 0.

Request
HideShow
Headers
X-Access-Token: YOUR_80_CHARACTERS_SESSION_TOKEN_STRING
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "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
  }
}
Response  401
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "error": {
    "code": "api.error.token_invalid",
    "message": "Token jest niepoprawny lub wygasł."
  }
}

Dodaj
POST/bugs{?namespace,status,limit,offset}

Wymagane: content. Opcjonalne: priority (0–1, domyślnie 0.5), status (domyślnie open), namespace.

Example URI

POST https://api.artisans.pl/bugs?namespace=KRK
URI Parameters
HideShow
namespace
string (optional) Example: KRK

Skrócona nazwa projektu. Pominięty — zwracane są wszystkie błędy.

status
string (optional) 

open, in_progress albo closed.

limit
number (optional) 

Liczba rekordów na stronie, 1–100. Domyślnie 10.

offset
number (optional) 

Ile rekordów pominąć. Domyślnie 0.

Request
HideShow
Headers
X-Access-Token: YOUR_80_CHARACTERS_SESSION_TOKEN_STRING
Content-Type: application/json
Body
{
  "content": "Przycisk „Zaloguj” nie reaguje na iPhone SE.",
  "priority": 0.85,
  "namespace": "KRK"
}
Response  201
HideShow
Headers
Location: /bugs/1001
Content-Type: application/json; charset=utf-8
Body
{
  "data": {
    "id": "1001",
    "content": "Przycisk „Zaloguj” nie reaguje na iPhone SE.",
    "priority": 0.85,
    "status": "open",
    "namespace": "KRK",
    "created_at": 1763459400,
    "updated_at": 1763459400
  }
}
Response  400
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "error": {
    "code": "error.validation",
    "message": "Pole content jest wymagane."
  }
}

Błąd

Pobierz
GET/bugs/{id}

Example URI

GET https://api.artisans.pl/bugs/1001
URI Parameters
HideShow
id
string (required) Example: 1001

Identyfikator błędu.

Request
HideShow
Headers
X-Access-Token: YOUR_80_CHARACTERS_SESSION_TOKEN_STRING
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "data": {
    "id": "1001",
    "content": "Przycisk „Zaloguj” nie reaguje na iPhone SE.",
    "priority": 0.85,
    "status": "open",
    "namespace": "KRK",
    "created_at": 1763459400,
    "updated_at": 1763459400
  }
}
Response  404
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "error": {
    "code": "api.error.bug_not_found",
    "message": "Nie znaleziono błędu o id 1001."
  }
}

Uaktualnij
PUT/bugs/{id}

Zmieniane są tylko przesłane pola.

Example URI

PUT https://api.artisans.pl/bugs/1001
URI Parameters
HideShow
id
string (required) Example: 1001

Identyfikator błędu.

Request
HideShow
Headers
X-Access-Token: YOUR_80_CHARACTERS_SESSION_TOKEN_STRING
Content-Type: application/json
Body
{
  "priority": 0.3,
  "status": "closed"
}
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "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

DELETE https://api.artisans.pl/bugs/1001
URI Parameters
HideShow
id
string (required) Example: 1001

Identyfikator błędu.

Request
HideShow
Headers
X-Access-Token: YOUR_80_CHARACTERS_SESSION_TOKEN_STRING
Response  204

Biblioteka

Lista książek

Pobierz listę
GET/books{?q,limit,offset}

Example URI

GET https://api.artisans.pl/books
URI Parameters
HideShow
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.

Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "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

Pobierz
GET/books/{id}

Example URI

GET https://api.artisans.pl/books/dbc173e55fad441bb15195d16954f05c
URI Parameters
HideShow
id
string (required) Example: dbc173e55fad441bb15195d16954f05c

Identyfikator książki (32 znaki).

Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "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
  }
}
Response  404
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "error": {
    "code": "api.error.book_not_found",
    "message": "Nie znaleziono książki."
  }
}

Lokalizacja

Państwa

Lista państw
GET/countries

Obiekt: dwuliterowy kod ISO 3166-1 → polska nazwa, posortowany po nazwie.

Example URI

GET https://api.artisans.pl/countries
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
 "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

GET https://api.artisans.pl/cities?country_code=pl
URI Parameters
HideShow
country_code
string (optional) Example: pl

Dwuliterowy 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.

Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "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
  }
}
Response  400
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "error": {
    "code": "api.error.invalid_country_code",
    "message": "Parametr country_code musi mieć 2 litery (ISO 3166-1)."
  }
}

Artisans API · https://api.artisans.pl · dane przykładowe, kursy nie są prawdziwymi kursami rynkowymi