Apiary

Čo to je?

Apiary.io je nastroj na dokumentaciu REST API. Stale je to beta veria, treba na to mysliet.

Documentation

Organized around resources, code samples with syntax highlight, easy to explore.

Server Mock

The fastest way to static API prototype—just ‘document’ your future API and it’s up.
2 minutes to Hello World.

Inspector

Users can make API calls through apiary.io, we show them how they differ from documentation.

Kedy to použiť

Ked sa tvori REST API, sluzi na popis rozhrania. Tento popis moze byt potom odovzdany pouzivatelom API.<br />
Vyhodou je aj moznost vyuzitia Mock serveru, ktory apiary poskytuje. Podla popisu vygeneruje v dokumentacii request a response a ponukne URL adresu Mock servru.
Ak zadame spravny equest na spravnu URL, vrati sa nam response z dokumentacie.<br />
Da sa teda vyvijat aplikacie bez nutnosti mat implementovane REST API, ktore bude vyuzivane.

Ako to použiť

•  v Settings na apiary.io nastavit ci ma byt dokumentacia private, a ci ma byt aj mock server private (Private traffic)
• na apiary.io napisat dokumentaciu REST API vo forme blue print
• zaverzovat si tento blueprint u seba (SVN)
• vygenerovanie si HTML dokumentacie z verzie blueprintu ktory potrebujeme (moze byt odoslana pouzivatelom API)
• prevolavanie mock serveru

Syntax a generovanie dokumentacie

Jazyk, v ktorom sa dokumentacia Vasho API popisuje je  blueprint.
Komentare v tomto popise su zapisovane syntaxou markdown.

Generovanie dokumentacie

Perl skript na generovanie HTML verzie z Blueprint je markdown.
Priklad vygenerovania dokumentacie:

perl Markdown.pl jatBluepirnt.txt > htmlFromBlueprint.html

Rady od Apiary

Private Mock server

• Přemýšleli jsme jak omezit přístup k mock serveru aby to ovšem neovlivnilo API interakci. Nakonec je výsledkem setting "Private Traffic" (pravda, mohl být pojmenován možná lépe), který generuje náhodný username pro každého čtenáře API dokumentace (a defaultní, arbes.apiary.io, neexistuje).

Otazky a odpovede

Pochopil som ze projekt je este vo forme beta verzie, planuje sa potom napriklad nejake spoplatnenie tej sluzby, s tym ze budete mat napríklad garantovanu dostupnost tychto servrov?

• Ano. Již nyní mají někteří naši firemní uživatelé s námi už nyní mají komerční smlouvy včetně SLAs. Pokud u vás Apiary plní důležitou roli, rád si s vámi zavolám a dohodneme se na podmínkách.

Da sa stiahnut dokumentacia vo forme html, pdf alebo nieco podobne? Alebo si mozme u nas uchovavat iba skopirovany blueprint?

• PDF export momentálně nepodporujeme. HTML výstup je vidět na docs.<vaše-doména>.apiary.io. Stahování/archivace na vaší straně není něco, co předpokládáme - ale rozhodně by to technicky šlo (stejně tak jako např. konverze onoho HTML do PDF u vás).

Mock server bude vždy iba u Vas na Vasej strane?

• Ano, stejně jako dokumentace i mock server a proxy server s debuggerem jsou hostovány na našich serverech. Naše výpadky jsou již nyní tak ojedinělé, že doufáme, že je pravděpodobně ani nezaznamenáte. Nicméně i tento stav je pro nás neakceptovatelný a pracujeme na výrazně vyšší spolehlivosti.

Ide mi o to, ci je mozne sa spoliehat na dany server na ktorom bezi mock server. Z hladiska odstavok, nefunkcnosti servru a podobne by sme mohli mat problemi pri implementacii kodu, ktory sa spolieha na tieto mock-y.

• Apiary spadá do stejné kategorie jako celá řada dalších obdobných hostovaných business-služeb (GitHub, Zendesk, Salesforce apod.) - celý náš produkt je nabízen jako služba přes internet. Časem pro větší korporátní zákazníky budeme nabízet on-site instalace, ale není to něco, co bych vám mohl nabídnout nyní.

Kontakty

apiary.io - The place to keep your APIs
Jakub Nesetril
founder & CEO
@jakubnesetril
+420777274242
jakub@apiary.io - na tomto maily Jakub Nešetřil zatial odpoveda vzdy a velmi rychlo.