Merge pull request #146 from noi-techpark/issue-123-AlpineBits

Issue 123 alpine bits

source/datasets.rst

@@ -487,9 +487,7 @@ The following information is provided for each dataset in the Tourism domain:
    :strong:`MobileStation` which is a mobile probe no longer
    active. It will always return an empty set of values, because
    historical data are not available in the Open Data Hub.
-
-.. HGV datasets
-
+
 .. _package-dataset:
 
 .. dropdown:: :strong:`it.hgv.package`
@@ -599,3 +597,10 @@ Creative Industries
 NOI-Place
 ~~~~~~~~~
 .. include:: /datasets/noiplace.rst
+
+.. _alpinebits-dataset:
+
+https\://alpinebits.opendatahub.bz.it/AlpineBits
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. include:: /datasets/alpinebits.rst
+

source/datasets/alpinebits.rst

@@ -0,0 +1,19 @@
+.. alpinebits
+
+This endpoint provides data from the `AlpineBits Open Standard
+<https://www.alpinebits.org>`_, whose purpose it to ease B2B data exchange among
+actors involved in the alpine tourism.
+
+Documentation for developers, including sample code snippets and additional
+material can be found on AlpineBits dedicated page for developers
+https://www.alpinebits.org/developers/.
+
+Various development and testing tools can be found on
+http://development.alpinebits.org/#/home.
+
+===================== =================================================
+Output                 XML, multipart/form-data
+E-mail contact         help@opendatahub.bz.it
+AlpineBits versions    v2017-10, v2018-10 (coming soon 2020-10)
+AlpineBits Endpoint    https://alpinebits.opendatahub.bz.it/AlpineBits
+===================== =================================================

source/howto.rst

@@ -7,7 +7,6 @@ This page contains the list of available howtos, divided into
 areas. The list of howtos, together with a short description is
 available here:
 
-
 .. panels::
 
    .. toggle:: Mobility
@@ -32,9 +31,11 @@ available here:
 	 provided within the Tourism domain.
       #. :doc:`/howto/tourism/tips` Mini howtos, tricks&tips, and
 	 use cases for data in the Tourism domain.
+      #. :doc:`howto/tourism/alpinebits` access AlpineBits data
 
    -----
    :column: col-sm-12
+
 
    .. toggle:: Miscellaneous
 
@@ -71,3 +72,4 @@ available here:
    howto/noievents
    howto/tourism/tips
    howto/webcomponents
+   howto/tourism/alpinebits

source/howto/tourism/alpinebits.rst

@@ -0,0 +1,130 @@
+.. _ab-howto:
+
+How to access Open Data Hub AlpineBits Server as a client
+=========================================================
+
+The AlpineBits Alliance strives to develop and to spread a standard
+format to exchange data. In this howto, we show how to retrieve data
+from the AlpineBits Server endpoint for the Open Data Hub located at
+https://alpinebits.opendatahub.bz.it/AlpineBits, by using the (Linux)
+command line--in particular the :command:`curl` application, and the
+popular `Postman` API development environment.  An example call can be
+seen :ref:`at the bottom <ab-request>` of this section.
+
+.. note:: Alternative command line programs like :command:`wget` can
+   be used as well: simply adapt the parameters described in the
+   remainder of this section.
+
+The first important thing to mention is that requests to this endpoint
+need a :strong:`POST` method and an authentication token, therefore
+you should specify options :literal:`--request POST` and a header
+requiring `Basic` authorization and containing your token:
+:literal:`--header 'Authorization: Basic <your-email-address>'`
+
+.. note:: While there is no authorization required to access the Open Data
+   Hub AlpineBits Server, we strongly suggest you to insert as token
+   your email address for debugging reasons. It will help trace your
+   calls in the case you require support from the Open Data Hub Team.
+
+Next, it is necessary to provide the correct `client protocol version`
+and a `client ID`, which are two additional headers, namely
+:literal:`--header 'X-AlpineBits-ClientProtocolVersion: 2017-10'` and
+:literal:`--header 'X-AlpineBits-ClientID: 'My test request'`.
+
+Concerning the client protocol version, it must be one of the
+supported version mentioned in :numref:`ab-matrix`, which also
+shows the actions that can be used together with the protocol.
+
+.. _ab-matrix:
+
+.. table:: Matrix of the protocol versions and supported actions in
+   the AlpineBits implementation of the Open Data Hub.
+
+   +--------------------------+---------+---------+---------+---------+
+   | Open Data Hub AlpineBits | 2017-10 | 2017-10 | 2018-10 | 2018-10 |
+   | Server Actions           |   PUSH  |   PULL  |   PULL  |   PUSH  |
+   +--------------------------+---------+---------+---------+---------+
+   | FreeRooms                | Yes     | No      | Yes     | No      |
+   +--------------------------+---------+---------+---------+---------+
+   | GuestRequests            | --      | --      | --      | --      |
+   +--------------------------+---------+---------+---------+---------+
+   | Inventory Basic          | Yes     | Yes     | Yes     | Yes     |
+   +--------------------------+---------+---------+---------+---------+
+   | Inventory HotelInfo      | Yes     | Yes     | Yes     | Yes     |
+   +--------------------------+---------+---------+---------+---------+
+   | RatePlans                | --      | --      | --      | --      |
+   +--------------------------+---------+---------+---------+---------+
+   | BaseRates                | --      | --      | --      | --      |
+   +--------------------------+---------+---------+---------+---------+
+
+Note that PUSH and PULL refer to the action of uploading to and
+downloading from AlpineBits Server, respectively.
+
+Finally, to retrieve data from the AlpineBits Server, you need to set
+the correct content type (i.e., `multipart/form-data`) and provide an
+`action`. The content type is specified in another header by
+:literal:`--header 'Content-Type: multipart/form-data'`, while the
+action is given as a form: :literal:`--form 'action=getVersion'`.
+
+.. _ab-request:
+
+Summing up what was described above, a call to the AlpineBits Server endpoint
+looks like the following one:
+
+.. code-block:: 
+		
+   curl --location --request POST \
+   'https://alpinebits.opendatahub.bz.it/AlpineBits' \
+   --header 'Authorization: Basic <your-token-here>' \
+   --header 'X-AlpineBits-ClientProtocolVersion: 2017-10' \
+   --header 'X-AlpineBits-ClientID: 'My test request' \
+   --header 'Content-Type: multipart/form-data' \
+   --form 'action=getVersion'
+
+Here, you can see that the additional option :literal:`--location` is
+used, that will make sure to resend the request in case a
+:strong:`3xx` HTTP error code is received, i.e., if the requested
+resource has been moved.
+
+Postman Setup
+-------------
+
+In Postman, you need to enter the same data as in the call shown in
+previous section. The Postman setup equivalent to that call is shown
+in the two screenshots.
+
+.. _ab-postman-header:
+
+.. figure:: /images/postman/AB-postman1.png
+
+   Definition of the call's headers.
+
+In the headers you need to add all the parameters as in the curl
+version, except for the authentication: this option need to be
+specified in the `Authorization` tab of postman. Here, choose
+:strong:`Basic Auth` as type and use :strong:`someuser` and
+:strong:`secret`  as username and password, respectively.
+
+.. note:: It is suggested to use, instead of `someuser` and `secret`,
+   your contact information, in order to be able to contact you for
+   some technical reasons.
+
+Next, you need to add, in Postman's `Body` tab, the :literal:`action`.
+Choose :strong:`form-data`, enter :strong:`action` as key and the name
+of the method to retrieve data, in our example :strong:`getVersion`.
+
+.. _ab-postman-body:
+
+.. figure:: /images/postman/AB-postman2.png
+
+   Definition of the `action` and the outcome of the call.
+
+Once done, make sure to select :strong:`POST`, then click on
+:button:`Send` and you will receive the result in the bottom part of
+Postman's window, like in :numref:`ab-postman-body`.
+
+.. seealso:: More information about the interaction with AlpineBits
+   can be found in the official documentation, available at
+   https://www.alpinebits.org/developers/.
+
+