Ne všichni děláme integrace každý den. Proto jsme pro vás připravili rychlokurz integrace v dnešním světě, kde stručně zmiňujeme ty nejdůležitější pojmy a nástroje . Až se vším prokousáte, můžete pokračovat na příklady volání pro integraci s využitím tzv. REST API.
Technická informace k verzi TLS
| Table of Contents |
|---|
Základní principy a pojmy
Co potřebuje mít člověk v hlavě, aby rozuměl věcem kolem API:
Komunikace po internetu https://everything.curl.dev/protocols/network
Internetové protokoly https://everything.curl.dev/protocols/protocols
EndPoint - https://en.wikipedia.org/wiki/Web_API
REST- https://en.wikipedia.org/wiki/Representational_state_transfer https://zdrojak.cz/clanky/rest-architektura-pro-webove-api/
...
Postman
Postman je služba, která umožňuje ve velmi přátelském, srozumitelném prostředí textovat volání REST API rozhraní. Jednoduše si můžete organizovat různá volání, u každého volání přehledně zadáváte adresyu, typ volání, head, autorizaci, body, vidíte i výsledky volání. Využívá ji i Signi na https://signiapi.postman.co/.
Volání
Pro každé volání volíte:
V záhlaví požadavku se volí typ HTTP Request, typicky GET nebo POST .
V záhlaví požadavku se také uvádí adresa endpointu je v případě Signi API ná např. enpoind pro odeslání souboru k podpisu https://api.signi.com/api/v1/contract/ .
V případech, kdy enpoind má parametry, zadávají se na záložce Param, V případě Signi API např. endpoint založení souboru má parametr Type s hodnotou ”doc” tj. výsledná adresa je volání je https://api.signi.com/api/v1/contract/?type=doc .
Na záložce Autorization je jako typ autorizace zvolen jako typ autorizace API Key a jako hodnota klíče x-api-key je uveden API klíč workspace a umístění API klíče je zvoleno Header. API klíč pro váš workspace v Signi si vygenerujete dle návodu Generování API klíče.
Na záložce Body je jako typ volání zvoleno multipart/form-data a jsou uvedeny jeden či více Keys , což které mohou být buď typu text nebo file. V případě enpointu pro odeslání souboru k podpisu se předpokládají minimálně dva, data a uploaded_file_key. Pozor, oba dva jsou typu file , aby se do HTTP požadavku opravdu fyzicky přenesli soubory. V prvním je JSON s parametry volání endpointu, v druhém je soubor k podpisu - PDF anebo DOC, DOCX, XLS, XLSX, HTML. U každého klíče je třeba zvolit typ parametru je File, Klepnutím na “Select Files” se otevře výběr souboru, vložíte příslušný.
Tlačítkem Send se odesílíá požadavek na příslušné REST API. V dolním panelu pro zobrazení výsledku se ukazuje výsledek volání tj. obsah HTTP Response.
Tlačítkem Save se ukládá požadavek do Postmana pro opakované použítí.
Klíče na záložce Body jsou typu “File”, soubor k zaslání v požadavku se vybere z vašeho disku a nahraje přes “Select Files”.
Výsledek
Po odeslání požadavku tlačítkem Send se zobrazí v dolním panelu výsledku se ukazuje výsledek volání endpointu daného REST API. tj. obsah HTTP Response.
V případě úspěchu se objevuje kód 200 s příslušným komentářem. V případ ěchyby typicky kód 4xx nebo 5xx. Pi volání Signi API jsou nečastějšíá tyto chyby.
...
Curl
Pokkud jste spíše příznivcem příkazového řádku, mohl by vám vyhovovat pro účely testování volání REST API rozhraní Curl. Curl je open source program pro přenos dat přes různé internetové protokoly. Jeho příkazy se používají k popisu toho, jak se jaká data se při integraci přenáší. Stejně tak lze příkazy v programu spustit.
HTTP POST https://everything.curl.dev/http/post
HTTP Multipart formposts https://everything.curl.dev/http/multipart
HTTP cheat sheet - https://everything.curl.dev/http/cheatsheet
Seznam všech příkazů - https://curl.se/docs/manpage.html
...
hide progress
-s
...
verbose
-v
--trace-ascii <file>
...
extra info
-w "format"
...
output
-O
-o <file>
...
timeout
-m <seconds>
...
POST
-d "string"
-d @file
...
POST encoded
--data-urlencode
"[name]=val"
...
multipart formpost
-F name=value
-F name=@file
...
PUT
-T <file>
...
HEAD (ers too)
-I
-i
...
custom method
-X "METHOD"
...
read cookiejar
-b <file>
...
write cookiejar
-c <file>
...
send cookies
-b "c=1; d=2"
...
user-agent
-A "string"
...
proxy
-x <host:port>
...
add/remove headers
-H "name: value"
-H "name:"
...
custom address
--resolve
<host:port:addr>
...
smaller data
--compressed
...
insecure HTTPS
-k
...
Basic auth
-u user:passwd
...
follow redirects
-L
...
parallel
-Z
...
generate code
--libcurl <file>
list options
--help
...
...
...
...
Curl je většinou již součástí operačního systému - např. MS Windows, kde se spouští z aplikace Příkazová řádka, jež se spouští vyhledáním “cmd” ve vyhledávacím poli na pracovní ploše.
...
Curl příkaz spuštěný z příkazové řádky na MS Windows a jeho výsledek
Apiary
Apiary je jedna ze služeb sloužících pro zveřejňování dokumentace API. Využívá ji i Signi na https://signi.docs.apiary.io/
...
Příklad popisu endpointu “Autorizace > x-api-key > Detail uživatele”,
při volbě cURL v pravém panelu je vidět sada příkaz curl, stejně tak je možné zvolit jiná prostředí
Postman
Postman je jedna ze služeb pro testování volání API. Využívá ji i Signi na https://signiapi.postman.co/.
...
Příklad volání endpointu Detail uživatele
Technická informace k verzi TLS
Server chce:
# TLS 1.2 (suites in server-preferred order)
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 (0xc02f) ECDH x25519 (eq. 3072 bits RSA) FS 128
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (0xc030) ECDH x25519 (eq. 3072 bits RSA) FS 256
TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 (0xcca8) ECDH x25519 (eq. 3072 bits RSA) FS 256
Client umí:
TLS 1.2 ECC GCM cipher suites:
TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256_P256
TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256_P384
TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256_P521
TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384_P384
TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384_P521
Podle RFC https://datatracker.ietf.org/doc/html/rfc5289 jsou všechny ty algoritmy z 2008.
Zda je deprecated/obsolete bohužel nejde poznat.
Po hledání jsme zjistili, že pro Win2012R2 neexistuje:
...
Příklady volání Signi API
Až se prokousáte základy REST API, můžete pokračovat na příklady volání API anebo Pokročilé příklady volání Signi API . Pokud ještě tápete, napište nám na help@signi.com .