[[oktatas:web:rest_api|< REST API]]

====== Insomnia ======

  * **Szerző:** Sallai András
  * Copyright (c) Sallai András, 2022, 2023
  * Licenc: [[https://creativecommons.org/licenses/by-sa/4.0/|CC Attribution-Share Alike 4.0 International]]
  * Web: https://szit.hu

===== Az Insomnia =====

Az Insomnia API tervezését és tesztelését, dokumentálást 
lehetővé tevő GUI program.

===== Weboldal =====

  * https://insomnia.rest/

Letöltés:
  * https://insomnia.rest/download
===== Első lépések =====

Az Insomnia első indulásakor egy "Dashboard" nevű felület jelenik meg.
Egy Dashboard egy projekthez tartozik. Projektet a bal felső 
sarokban lehet létrehozni.

A Dashboardon belül
a jobb felső sarokban egy "Create" nevű gomb van. Itt két lehetőségünk van:
  * Lekérdezés gyűjtemény létrehozása
  * Dokumentáció létrehozása

===== Telepítés Windowson =====

Letölthetjük a weboldalról a telepítőt; a telepítéshez nem szükséges
rendszergazdai jog. 

Telepítés chocolatey csomagkezelővel:
  choco install insomnia-rest-api-client
===== Telepítés Debian GNU/Linuxon =====

Látogassuk meg a letöltésoldalt:
  * https://insomnia.rest/download

Érdemes a "See all downloads" lehetőséget (apró betűvel) választani.


Debian GNU/Linuxon a .deb csomagnak teljesíthetetlen függőségei vannak,
ezért válasszuk inkább a .tar.gz kiterjesztésű fájlt. 

Csomagoljuk ki az Insomnia-t az /opt könyvtárba. 
Kapunk egy ehhez hasonló könyvtárat:
  Insomnia.Core-2021.5.3
Újabb verzió esetén a 2021.5.3 helyén más értékek állnak.

A könyvtárban találunk egy insomnia nevű indítható programot. 
A programot, érdemes szimbolikusan linkelni a következő könyvtárba:
  /usr/local/bin
Példa a linkelésre, a fenti könyvtárnév mellett:
  ln -s /opt/Insomnia.Core-2021.5.3/insomnia /usr/local/bin/insomnia


Így parancssorból bárhonnan indítható.


===== Használat =====

==== Request Collection ====

A Request Collectionon belül mappákat hozhatunk létre, azon belül
kéréseket:
<code>
Request Collection
  `-Folder
      `-Request
</code>


Minden végpont számára érdemes létrehozni egy könyvtárat,
azon belül minden metódushoz egy kérést (Request).


{{:oktatas:web:rest:folder_request.png|}}

==== Kép feltöltés ====

  * Body > Multipart


===== Környezeti változók =====

Aktiváljuk a "No Environment" legördülő listadobozt. Ott válasszuk:
  * Manage Environments  Ctrl+E

Vegyük fel, például:

<code javascript>
{
  "host": "localhost:8000"
}
</code>

Zárjuk be.

Az URL helyet ezek után el kezdjük írni:

<code>
_.
</code>

Ezt követően felkínálja a beírt változókat.




===== Dokumentum készítés =====


Három fület találunk:
  * DESIGN  DEBUG  TEST

A DESIGN fülön:

<code yaml>
openapi: 3.0.0
info:
  title: Dolgozók kezelése
  version: '1.0'  
servers:
  - url: http://localhost:8000
paths:
  /employees:
    get:
      summary: read employees
      operationId: fetchEmployees
      responses:
        default:
          description: Megérkezett dolgozók
</code>

Amikor az **operationId** számára új értéket állítunk be a DEBUG fülön létrejön egy új bejegyzés.

A TEST fülön készíthetünk teszteket a kérésekhez.

<note tip>
Az elkészült dokumentum használja a környezetet, ezért a szerver változtatása esetén szükség lehet a **OpenAPI env** aktiválására.

</note>
===== Az inso =====


Telepítés:
  * https://docs.insomnia.rest/inso-cli/install (2023)


Ellenőrzés:
  ./inso --version


===== Linkek =====
  * [[https://www.digitalocean.com/community/tutorials/how-to-create-documentation-for-your-rest-api-with-insomnia|https://www.digitalocean.com/]] (2022)