findhotel-sapi v0.16.2
#+TITLE: SAPI SDK #+CATEGORY: sapi #+AUTHOR: SAPI Squad #+SETUPFILE: https://fniessen.github.io/org-html-themes/org/theme-readtheorg.setup #+HTML_HEAD: #content{max-width:1800px;} #+HTML_HEAD: p{max-width:800px;} #+HTML_HEAD: li{max-width:800px;}
SDK provides a high level TypeScript/JavaScript API for searching hotels, hotels' offers and rooms.
- Table of contents :noexport: :PROPERTIES: :TOC: :include siblings :depth 2 :ignore this :END: :CONTENTS:
- [#glossary]
- [#tutorials]
- [#api-reference]
- [#sapi-client]
- [#search-method]
- [#rooms-method] :END:
- How to work with this document :noexport:
See https://orgmode.org to learn about Org Mode markup language. It's greatly [https://karl-voit.at/2017/09/23/orgmode-as-markup-only/] (Markdown included).
To edit it's better to use [https://www.gnu.org/software/emacs/] (for macOS use either [https://github.com/railwaycat/homebrew-emacsmacport/releases], [https://github.com/d12frosted/homebrew-emacs-plus#install] or from [https://emacsformacosx.com]) but you can also use a plugin for VSCode, search for "Org Mode" on Marketplace, [https://marketplace.visualstudio.com/items?itemName=tootone.org-mode] looks sane.
If you're new to Emacs and use macOS, it's recommended to start with [https://github.com/freetonik/castlemacs], so install it using the below snippet:
#+begin_src sh brew install ripgrep aspell gnutls mv ~/.emacs.d ~/.emacs.d.bak git clone https://github.com/freetonik/castlemacs ~/.emacs.d #+end_src
It will enable regular shortcuts as in macOS, like Command-C for copy, Command-O for opening a file and so on.
If you're a vim user, there's [https://github.com/jceb/vim-orgmode] plugin, but the better option is to install [https://github.com/emacs-evil/evil] (Emacs VI Layer), which turns Emacs to be a better vim but keeping all Emacs' goodies.
However, in order to export this file to an HTML, you'll need Emacs and run the export (put cursor inside a code block and press =C-c C-c=, Control-C and Control-C again):
#+begin_src emacs-lisp (org-html-export-to-html) #+end_src
#+RESULTS: : README.html
To open =README.html= file in a browser, run:
#+begin_src sh open README.html #+end_src
#+RESULTS:
Sections tagged with =:noexport:= (like this one) won't be exported and present in ToC, but still visible on GitHub.
Then the file should be copied on S3:
#+begin_src sh aws s3 cp README.html s3://fh-sapi-docs/index.html #+end_src
#+RESULTS: : Completed 32.2 KiB/32.2 KiB (42.7 KiB/s) with 1 file(s) remaining upload: ./README.html to s3://fh-sapi-docs/index.html
so it's available online on [http://fh-sapi-docs.s3-website-eu-west-1.amazonaws.com/].
- Automatic publishing :noexport:
This file will be automatically published on S3 making it available live.
** TODO Setup Github Actions for the repo
It should publish README.org into html file in S3 bucket.
From =main= branch to =s3://fh-sapi-docs/index.html= Fron PR branch to =s3://fh-sapi-docs/pr-NNN/index.html=
[https://github.com/marketplace/actions/set-up-emacs] action step looks useful in the process.
** TODO Bring in all CSS/JS dependencies locally
- Glossary :PROPERTIES: :CUSTOM_ID: glossary :END:
Glossary contains terms that are used throuout the documentation.
- HotelId :: FindHotel hotel id
- Itinerary :: tuple of =hotelId=, =checkIn=, =checkOut=
- Tutorials :PROPERTIES: :CUSTOM_ID: tutorials :END:
** Getting Started :PROPERTIES: :CUSTOM_ID: getting-started :END:
First, install SAPI SDK via the [https://www.npmjs.com/get-npm] package manager:
#+begin_src sh npm install git://github.com/FindHotel/sapi.git #+end_src
Then, import SAPI into your project:
#+begin_src js import sapi from '@daedalus/sapi' #+end_src
Create SAPI client:
#+begin_src js const clientId = 'client-id'
const clientKey = 'client-key'
const options = { anonymousId: 'fd9dbb5f-b337-4dd7-b640-1f177d1d3caa', language: 'en', currency: 'USD', userCountry: 'US' }
const sapiClient = await sapi(clientId, clientKey, options) #+end_src
Now SAPI client is ready to be used in your application.
For full documentation and supported options check [#sapi-client].
** Usage :PROPERTIES: :CUSTOM_ID: usage :END:
*** Hotels search :PROPERTIES: :CUSTOM_ID: tutorial-hotels-search :END:
Search for the hotels and hotels' offers:
#+begin_src js const searchParameters = { placeId: '47319', checkIn: '2021-10-10', checkOut: '2021-10-11', rooms: '2' }
const callbacks = { onStart: (response) => { console.log('Search started', response) }, onAnchorReceived: (response) => { console.log('Anchor received', response) }, onHotelsReceived: (response) => { console.log('Hotels received', response) }, onOffersReceived: (response) => { console.log('Offers received', response) }, onComplete: (response) => { console.log('Search completed', response) } }
const search = await sapiClient.search(searchParameters, callbacks) #+end_src
For full documentation, check [#search-method].
*** Get rooms :PROPERTIES: :CUSTOM_ID: tutorial-get-rooms :END:
Get rooms and rooms' offers:
#+begin_src js const rooms = await sapiClient.rooms({ hotelId: '47319', checkIn: '2021-10-10', checkOut: '2021-10-11', rooms: '2' }) #+end_src
For full documentation, check [#rooms-method].
- API Reference :PROPERTIES: :CUSTOM_ID: api-reference :END:
** SAPI client :Constructor: :PROPERTIES: :CUSTOM_ID: sapi-client :END:
Create SAPI client:
#+begin_src js const clientId = 'client-id'
const clientKey = 'client-key'
const options = { anonymousId: 'fd9dbb5f-b337-4dd7-b640-1f177d1d3caa', language: 'en', currency: 'USD', userCountry: 'US' }
const sapiClient = await sapi(clientId, clientKey, options) #+end_src
*** Supported options :PROPERTIES: :CUSTOM_ID: client-options :END:
| name | required | type | default | description | example | |------------------------+----------+--------------------------+---------+---------------------------------------------------------------------------------------------+----------------------------------------| | =anonymousId= | yes | =string= | | Unique ID identifying users | =2d360284-577b-4a53-8b91-68f72b9227fa= | | =language= | yes | =string= | =en= | 2-char language code | =en= | | =currency= | yes | =string= | =USD= | 3-char uppercased ISO currency code | =USD= | | =userCountry= | yes | =string= | =US= | 2-char uppercased ISO country code | =US= | | =deviceCategory= | yes | =string= | | =desktop= or =mobile= | =desktop= | | =includeLocalTaxes= | no | =boolean= | | Include or not local taxes based in the displayed price | =false= | | =includeTaxes= | no | =boolean= | | Include or not taxes based in the displayed price | =false= | | =variationIds= | yes | =Record<string, string>= | | A/B tests variation IDs (/can be empty object/) | ={hotel: 'ab-test-id-b'}= | | =initWithConfig= | no | =Record<string, any>= | | Used to override default config | | | =algoliaClientOptions= | no | =AlgoliaSearchOptions= | | Algolia client options used for debugging and setting additional options like timeouts etc. | |
** =search()= method :Method: :PROPERTIES: :CUSTOM_ID: search-method :END:
Search is a method of sapiClient for searching hotels and offers for provided =searchParameters=:
#+begin_src js const search = await sapiClient.search(searchParameters, callbacks) #+end_src
*** Search parameters :Parameters: :PROPERTIES: :CUSTOM_ID: search-parameters :END:
| name | required | type | description | example | |---------------+----------+------------------------------+-------------------------------+--------------------------------------| | =hotelId= | no | =string= | Hotel Id for hotel search | =1371626= | | =placeId= | no | =string= | Place Id for place search | =47319= | | =query= | no | =string= | Text query | =Amsterdam city= | | =geolocation= | no | ={lat: number, lon: number}= | Geolocation query | ={lat: 36.114303, lon: -115.178312}= | | =checkIn= | no | =string= | Check in date (=YYYY-MM-DD=) | =2021-10-10= | | =checkOut= | no | =string= | Check out date (=YYYY-MM-DD=) | =2021-10-11= | | =rooms= | no | =string= | Rooms configuration | =2= |
*** Callbacks :Parameters: :PROPERTIES: :CUSTOM_ID: search-callbacks :END:
Search method receives callbacks object as the second argument:
#+begin_src js const callbacks = { onStart: (response) => { console.log('Search started', response) }, onAnchorReceived: (response) => { console.log('Anchor received', response) }, onHotelsReceived: (response) => { console.log('Hotels received', response) }, onOffersReceived: (response) => { console.log('Offers received', response) }, onComplete: (response) => { console.log('Search completed', response) } } #+end_src
**** onStart(response) Runs at the beginning of the each new search\ =response= - /in progress.../
**** onAnchorReceived(response) Runs when SAPI receives anchor (and?) anchor hotel\ =response= - /in progress.../
**** onHotelsReceived(response) Runs when SAPI receives static search results\ =response= - /in progress.../
**** onOffersReceived(response) Runs when SAPI receives a bunch of offers\ =response= - /in progress.../
**** onComplete(response) Runs when current search is complete and all offers are retrieved\ =response= - /in progress.../
*** Response :Response: :PROPERTIES: :CUSTOM_ID: search-response :END:
/in progress.../
** =rooms()= method :Method: :PROPERTIES: :CUSTOM_ID: rooms-method :END:
Rooms is a method of sapiClient for retrieving rooms information and offers for a particular itinerary:
#+begin_src js const rooms = sapiClient.rooms({ hotelId: '47319', checkIn: '2021-10-10', checkOut: '2021-10-11', rooms: '2' }) #+end_src
*** Rooms query parameters :Parameters: :PROPERTIES: :CUSTOM_ID: rooms-parameters :END:
| name | required | type | default | description | example | |------------+----------+----------+---------+-------------------------------+--------------| | =hotelId= | yes | =string= | | Hotel Id to retrieve rooms | =1371626= | | =checkIn= | yes | =string= | | Check in date (=YYYY-MM-DD=) | =2021-10-10= | | =checkOut= | yes | =string= | | Check out date (=YYYY-MM-DD=) | =2021-10-11= | | =rooms= | yes | =string= | | Rooms configuration | =2= |
*** Response :Response: :PROPERTIES: :CUSTOM_ID: rooms-response :END:
/in progress.../
SAPI =rooms()= method will have the similar response body as BoFH API =/rooms= endpoint. For now please refer to [https://github.com/FindHotel/bofh-api/blob/master/docs/consumers/default/endpoints/rooms.md#example-1].