Definicja API Rest

Definicja odpowiedzi

API obsługuje TYLKO usługi RESTowe, które zwracają typ application/json .

Domyślny ContentType z jakim wysyłamy zapytania do usługi to application/json. Obsługiwany jest również multipart/form-data, jeżeli w nagłówku zostanie przekazany parametr {'Content-Type': 'multipart/form-data'}. Na przykład:

api.rest.v1.get('serviceId', {queryParams: {'key': 'value'}}, {'Content-Type': 'multipart/form-data'});

Odpowiedź z usługi wygląda następująco:

{
    status: {
        code: int,
        message: String
    },
    headers: Map<String, String>,
    body: Map<String, Object>
}

Wszystkie elementy w odpowiedzi są przetworzone jako natywne zmienne w JavaScript. Można się do nich dostać np. w ten sposób:

response.status.code   // <--- uzyskanie wartości z pola `code`, zawierającego kod odpowiedzi, np. 200
response.status.message   // <--- uzyskanie wartości z pola `message`, zawierającego wiadomość odpowiedzi, np. "Accepted"
 
response.headers.language    // <---  uzyskanie wartości nagłówka zwrotnego o nazwie `language`
 
response.body.user.type    // <--- uzyskanie wartości konkretnego pola z odpowiedzi, gdzie odpowiedź ma wygląd: {"user": {"type": "typUzytkownika"}}

Definicja wyjątku

W przypadku innego kodu zwrotnego, niż 2XX dostaniemy wyjątek możliwy do obsłużenia. Np. w sytuacji z kodem 404 (usługa nie dostępna lub błędny adres), kod 405 (niepoprawna metoda) lub kod 500 (błąd wewnętrzny po stronie usługi).

Wyjątek wygląda następująco:

{
    status: {
        code: int,
        message: String
    },
    body: String
}

Aby zweryfikować, czy jest to wyjątek do obsłużenia przez nas, możemy sprawdzić, czy złapany element posiada pola, które nas interesują.

try {
    // zawołaj usługę zewnętrzną
} catch (exception) {
    if (exception.status !== undefined && exception.status.code !== undefined) {
        // obsługa naszego wyjątku, np. zwrócenie wartości domyślnej
    } else {
        // to nie jest nasz wyjątek, możemy go obsłużyć lub puścić dalej
        throw exception;
    }
}

Definicja żądania

Żądanie może zostać sparametryzowane.

Żądania mogą zawierać payload:

api.rest.v1.post(SERVICE_ID, PATH, HEADER, PAYLOAD, TIMEOUTS);
api.rest.v1.put(SERVICE_ID, PATH, HEADER, PAYLOAD, TIMEOUTS);

Oraz mogą być bez payloadu:

api.rest.v1.get(SERVICE_ID, PATH, HEADER, TIMEOUTS);
api.rest.v1.delete(SERVICE_ID, PATH, HEADER, TIMEOUTS);

Poniżej definicja parametrów:

SERVICE_ID: String;  // <--- np. 'mojServiceId'
 
HEADER: Map<String, String>;  // <--- np. {'mojHeader': 'wartosc'}
 
PAYLOAD: Map<String, Object>;  // <--- dowolny, poprawny obiekt, np. {'user': 123, 'name': 'Lisa'}
TIMEOUTS: Map<String, Integer>;  // <--- obiekt definiujący timeouty dla  wywoływanej usługi np. {connectionTimeout: 2000, readTimeout: 2000}

Definicja PATH wygląda następująco:

{
    pathParams: List<String>,   // <--- kolejne elementy namiaru na usługę, np. ['api', 'v1', 'path', 'to', 'endpoint'] dla /api/v1/path/to/endpoint
    queryParams: Map<String, String> // <--- należy pamiętać, że query params to zawsze string
}

Definicja TIMEOUTS wygląda następująco:

{
    connectionTimeout: Integer,   // <--- limit czasu nawiązywania połączenia w milisekundach
    readTimeout: Integer // <--- limit czasu odczytu odpowiedzi w milisekundach
}

Brak TIMEOUTS

W momencie gdy obiekt TIMEOUTS nie zostanie zdefiniowany dla wykonanego zapytania REST zostaną nadane wartości zaczerpnięte z konfiguracji. Znajdują się one w parametrach:

</config>

Parametr:

default określa wartość zaciąganą gdy obiekt TIMEOUTS nie zostanie zdefiniowany
maximum określa maksymalną wartość jaką może ustawić LOW-CODE Developer podczas przygotowywania zapytania (jeśli ustawi większą niż podana zostanie ustawiona wartość maximum)

Przykładowe wykonanie żądań znajdują się w sekcjach niżej.

Żądania

Dla każdego z poniższych żądań zakładamy spójną konfigurację:

scriptservice:
  api:
    - serviceId: "serviceId"
      url: "http://moj.service/"