API docs standardization changes

.gitbook.yaml

@@ -1,10 +1,4 @@
 root: ./
 
-structure:
-  readme: README.md
-  summary: SUMMARY.md
-
 redirects:
-  booking-engine-guide/booking-engine-widget/integrations: integrations/README.md
-  booking-engine-guide/booking-engine-widget/integrations/google-tag-manager: integrations/google-tag-manager.md
-  booking-engine-guide/booking-engine-widget/integrations/google-triggers-reference: integrations/google-triggers-reference.md
+  booking-engine-api/guidelines/authorization: booking-engine-api/guidelines/authentication.md

FAQ/mews-li-migration.md

@@ -1,6 +1,8 @@
-# How to migrate booking engine off mews.li
+# Migration off the mews.li domain
 
-> ⚠️ Support for this outdated implementation was discontinued as of May 1 - we are not responsible for the functionality of the booking engine on this domain
+This is a guide to help you migrate your booking engine off the discontinued `mews.li` domain.
+
+> **Important:** Support for the old domain was discontinued in May 2024 - we are not responsible for the functionality of the booking engine on this domain.
 
 ## Standalone Booking Engine migration
 
@@ -39,4 +41,4 @@ Replace the domain in your booking engine loading script from `https://mews.li`
 ```
 After a successful migration, the keyword `mews.li` should no longer appear on your website.
 
-If you have any questions, please open a ticket from Mews Operations via our Mews Digital Assistant.
+If you have any questions, please open a ticket from __Mews Operations__ via the Mews Digital Assistant.

SUMMARY.md

@@ -16,11 +16,11 @@
   * [Reference](booking-engine-widget/reference.md)
   * [Troubleshooting](booking-engine-widget/troubleshooting.md)
 * [Booking Engine API](booking-engine-api/README.md)
-  * [Guidelines](booking-engine-api/guidelines/README.md)
+  * [Usage guidelines](booking-engine-api/guidelines/README.md)
+      * [Authentication](booking-engine-api/guidelines/authentication.md)
       * [Requests](booking-engine-api/guidelines/requests.md)
       * [Responses](booking-engine-api/guidelines/responses.md)
       * [Environments](booking-engine-api/guidelines/environments.md)
-      * [Authorization](booking-engine-api/guidelines/authorization.md)
       * [Images](booking-engine-api/guidelines/images.md)
       * [Supported currency codes](booking-engine-api/guidelines/supported-currency-codes.md)
       * [Supported language codes](booking-engine-api/guidelines/supported-language-codes.md) 
@@ -42,12 +42,13 @@
 * [Integrations](integrations/README.md)
   * [Google Tag Manager](integrations/google-tag-manager.md)
   * [Google Triggers Reference](integrations/google-triggers-reference.md)
-  * [Google Tag Manager - Configuration](integrations/gtm-skeleton.md)
+  * [Google Tag Manager Configuration](integrations/gtm-skeleton.md)
   * [Google Analytics cross-domain tracking](integrations/ga-cross-domain-tracking.md)
 * [FAQ](FAQ/README.md)
   * [Ways to integrate](FAQ/ways-to-integrate.md)
   * [Migration off the mews.li domain](FAQ/mews-li-migration.md)
 * [Changelog](changelog/README.md)
+	* [Changelog 2024](changelog/changelog2024.md)
 	* [Changelog 2023](changelog/changelog2023.md)
 	* [Changelog 2022](changelog/changelog2022.md)
 	* [Changelog 2021](changelog/changelog2021.md)

booking-engine-api/README.md

@@ -7,7 +7,7 @@ Use this option if you want to create your own custom booking engine.
 > We maintain an [OpenAPI definition](https://api.mews.com/swagger/distributor/swagger.json) (formerly Swagger) for the __Mews Booking Engine API__. You can use this to build out client applications using third party tools.
 > At this stage we consider this a Beta test version, but please use it and get in touch to let us know how you get on.
 
-* [Guidelines](guidelines/README.md)
+* [Usage guidelines](guidelines/README.md)
 * [Use cases](use-cases/README.md)
 * [API Operations](operations/README.md)
 * [Deprecations](deprecations/README.md)

booking-engine-api/deprecations/README.md

@@ -1,9 +1,8 @@
 # Deprecations
 
-Deprecations are features of the API which you are discouraged from using, even though they may still be supported for a period of time for the sake of backwards compatibility.
-Such features are normally deprecated because they are superseded by a better alternative. They can include object properties or entire API operations.
-The list of deprecations is as follows. Individual items are also highlighted in the [Changelog](../../changelog/README.md) when they occur.
-Historic deprecations that have already been discontinued may not be listed. For more information, see our [Deprecations Policy](https://mews-systems.gitbook.io/open-api/staying-up-to-date/deprecations-policy).
+Deprecations are features of the API which you are discouraged from using, even though they may still be supported for a period of time for the sake of backwards compatibility. Such features are normally deprecated because they are superseded by a better alternative. They can include object properties or entire API operations. The list of deprecations is as follows. Individual items are also highlighted in the [Changelog](../../changelog/README.md) when they occur. Historic deprecations that have already been discontinued may not be listed.
+
+**For more information, see our [Deprecations Policy](https://mews-systems.gitbook.io/open-api/staying-up-to-date/deprecations-policy).**
 
 > **Important:** We strongly advise you to review this list and if you are using any of the deprecated items in your integration, to update your implementation accordingly.
 
@@ -14,7 +13,7 @@ The table columns have the following meanings:
 * __Replaced by__ \- What the replacement is, if applicable
 * __Context__ \- The context in which the property is used, usually the API operation
 * __Deprecated__ \- The date at which the deprecation notice was given (see the [Changelog](../../changelog/README.md))
-* __Discontinued__ \- The date at which it is planned to discontinue support completely; a value of '-' indicates no date has been set
+* __Discontinued__ \- The date at which it is planned to discontinue the feature completely; a value of '-' indicates no date has been set
 
 ## Deprecated object properties
 

booking-engine-api/guidelines/README.md

@@ -1,13 +1,13 @@
-# Guidelines
+# Usage guidelines
 
 This section provides guidelines and general information on how to use the __Mews Booking Engine API__. For information about individual endpoints or operations, see [API Operations](../operations/README.md).
 
 > **Important:** The Mews Booking Engine API is designed to be consumed directly by front-end clients. It is unsuitable for continuous polling by a single server due to its built-in anti-scraping protection and such requests can fail. For server to server communication, please refer to the [Mews Connector API](https://mews-systems.gitbook.io/connector-api/).
 
+* [Authentication](authentication.md)
 * [Requests](requests.md)
 * [Responses](responses.md)
 * [Environments](environments.md)
-* [Authorization](authorization.md)
 * [Images](images.md)
 * [Supported currency codes](supported-currency-codes.md)
 * [Supported language codes](supported-language-codes.md)

booking-engine-api/guidelines/authentication.md

@@ -0,0 +1,36 @@
+# Authentication
+
+The __Mews Booking Engine API__ is a public API that requires client authentication and authorization. 
+
+## Client authentication
+
+Authentication is the process of verifying the identity of the client. To access the API, you must identify your client application by providing the `Client` property in all requests. This ensures that your client application is recognized and allowed to interact with the API.
+
+### Pre-registered
+
+Your client application needs to be pre-registered with Mews Support. You can open a ticket from __Mews Operations__ via the Mews Digital Assistant. The registration request should contain:
+
+* `Client` - the name of the client application that will be used for every API request
+* `Email` - an email contact for your development department; this email will be used by our developers to notify you about any breaking changes in the API
+* `Environment` - the name of the environment you are accessing, either `Production` or `Demo`.
+
+### Environments
+
+We offer two environments, `Production` and `Demo`. Use `Demo` during API implementation, and `Production` only for live customer sites.
+The two environments have separate client lists, so make sure you are registered in `Production` before you move your implementation to the Production environment.
+For details, see our [Environments](environments.md) page.
+
+### Sample client name
+
+Before the registration of your `Client` name is confirmed, you can use the sample client name below. This client name will **only work in the Demo environment**.
+Keep in mind that this must be replaced by your proper `Client` name as soon as you finish the registration process.
+
+```json
+{
+    "Client": "My Client 1.0.0"
+}
+```
+
+## Client authorization
+
+Authorization is the process of determining what the authenticated client is allowed to do. In this case, it is sufficient to know the unique identifier of a hotel or other enterprise in order to access it. However, the client must be authenticated by providing the `Client` property in all requests to ensure it has the necessary permissions to interact with the API.

booking-engine-api/guidelines/environments.md

@@ -23,6 +23,6 @@ This is the live production environment.
 * **Hotel Id** - This depends on the hotel and should be provided to you by the hotel administrator.
 * **Configuration Id** - This depends on the hotel setup and can be found in **Mews Operations** administration.
 
-## Whitelisting
+## IP address allowlisting
 
-Whitelisting (also called 'allowlisting') is a common security measure which can be applied to a system to allow only specified external systems to talk to it. This has traditionally been achieved using IP address-based firewall rules. However, this approach does not work with modern cloud based architectures, which use dynamic and shared IP addresses, proxy servers and elastic resources. For this reason, we do not support the use of IP address whitelists for our APIs and we cannot supply a list of IP addresses for our APIs.
+Allowlisting (formerly 'whitelisting') is a common security measure which can be applied to a system to allow only specified external systems to talk to it. This has traditionally been achieved using IP address-based firewall rules. However, this approach does not work with modern cloud based architectures, which use dynamic and shared IP addresses, proxy servers and elastic resources. For this reason, we do not support the use of IP address allowlists for our APIs and we cannot supply a list of IP addresses for our APIs.

booking-engine-api/guidelines/requests.md

@@ -22,11 +22,11 @@ The API accepts only `HTTP POST` requests with `Content-Type` set to `applicatio
     "CultureCode": null 
 }
 ```
-| Property       | Type   | Contract | Description                                                                      |
-|:---------------|:-------|:---------|:---------------------------------------------------------------------------------|
-| `Client`       | string | required | Identification of the Client as described in [Authorization](./authorization.md) |
-| `LanguageCode` | string | optional | Code of the language. [Supported language codes](./supported-language-codes.md)  |
-| `CultureCode`  | string | optional | Code of the culture                                                              |
+| Property | Type | Contract | Description |
+|:--|:--|:--|:--|
+| `Client` | string | required | Identification of the client, as described in [Authentication](./authentication.md). |
+| `LanguageCode` | string | optional | Code of the language, see [Supported language codes](./supported-language-codes.md). |
+| `CultureCode` | string | optional | Code of the culture, see [Supported language codes](./supported-language-codes.md). |
 
 * All API operations require `Client` to be present in the request.
 * All API operations optionally accept `LanguageCode` and `CultureCode`. These can be used to enforce the language and culture of the operation, which affects for example the names of entities, descriptions or error messages.

booking-engine-api/operations/availability-blocks.md

@@ -22,7 +22,7 @@ Availability blocks can restrict your booking engine's calendar to specific inte
 
 | Property | Type | Contract | Description |
 | :-- | :-- | :-- | :-- |
-| `Client` | string | required | Identification of the API client, as described in [Authorization](../guidelines/authorization.md). |
+| `Client` | string | required | Identification of the API client, as described in [Authentication](../guidelines/authentication.md). |
 | `EnterpriseId` | string | required | Unique identifier of the hotel (enterprise). |
 | `AvailabilityBlockIds` | array of string | required | Set of unique identifiers of the Availability Blocks for which you want to get the details. |
 

booking-engine-api/operations/configuration.md

@@ -22,7 +22,7 @@ This operation can be called initially to fetch data which may be important duri
 
 | Property | Type | Contract | Description |
 | :-- | :-- | :-- | :-- |
-| `Client` | string | required | Identification of the API client, as described in [Authorization](../guidelines/authorization.md). |
+| `Client` | string | required | Identification of the API client, as described in [Authentication](../guidelines/authentication.md). |
 | `PrimaryId` | string | required | Unique identifier of the primary [Configuration](#configuration-1). |
 | `Ids` | array of string | required | Set of unique identifiers of [Configurations](#configuration-1). |
 

booking-engine-api/operations/hotels.md

@@ -17,7 +17,7 @@ Get hotels data for a single specified hotel. This operation can be called initi
 
 | Property | Type | Contract | Description |
 | :-- | :-- | :-- | :-- |
-| `Client` | string | required | Identification of the client, as described in [Authorization](../guidelines/authorization.md). |
+| `Client` | string | required | Identification of the client, as described in [Authentication](../guidelines/authentication.md). |
 | `HotelId` | string | required | Unique identifier of the hotel. |
 
 ### Response
@@ -415,7 +415,7 @@ The availability and pricing is returned for each applicable combination of occu
 
 | Property | Type | Contract | Description |
 | :-- | :-- | :-- | :-- |
-| `Client` | string | required | Identification of the client as described in [Authorization](../guidelines/authorization.md). |
+| `Client` | string | required | Identification of the client as described in [Authentication](../guidelines/authentication.md). |
 | `ConfigurationId` | string | required | Unique identifier of the used Distributor configuration. |
 | `HotelId` | string | required | Unique identifier of hotel. |
 | `StartUtc` | string | required | Reservation start date \(arrival date\) in ISO 8601 format. |
@@ -613,7 +613,7 @@ Fetch payment configuration parameters for the specified hotel.
 
 | Property | Type | Contract | Description |
 | :-- | :-- | :-- | :-- |
-| `Client` | string | required | Identification of the client as described in [Authorization](../guidelines/authorization.md). |
+| `Client` | string | required | Identification of the client as described in [Authentication](../guidelines/authentication.md). |
 | `HotelId` | string | required | Unique identifier of hotel. |
 
 ### Response

booking-engine-api/operations/reservation-groups.md

@@ -54,7 +54,7 @@ Create a group of one or more reservations, i.e. make a reservation.
 
 | Property | Type | Contract | Description |
 | :-- | :-- | :-- | :-- |
-| `Client` | string | required | Client application name, as described in [Authorization](../guidelines/authorization.md). |
+| `Client` | string | required | Client application name, as described in [Authentication](../guidelines/authentication.md). |
 | `ConfigurationId` | string | required | Unique identifier of the Booking Engine configuration used. |
 | `HotelId` | string | required | Unique identifier of the hotel. |
 | `Customer` | [Customer](#customer) | required | Information about the customer or guest. |
@@ -216,7 +216,7 @@ Fetch details of the specified reservation group.
 
 | Property | Type | Contract | Description |
 | :-- | :-- | :-- | :-- |
-| `Client` | string | required | Client application name, as described in [Authorization](../guidelines/authorization.md). |
+| `Client` | string | required | Client application name, as described in [Authentication](../guidelines/authentication.md). |
 | `HotelId` | string | required | Unique identifier of the hotel. |
 | `ReservationGroupId` | string | required | Unique identifier of the reservation group. |
 | `Extent` | [Reservation group extent](#reservation-group-extent) | optional | Extent of data to be returned. e.g. it is possible to specify that together with the reservation group, payment requests and payments will be returned. |

booking-engine-api/operations/reservations.md

@@ -35,7 +35,7 @@ Get a price quotation for a specific hotel, date interval, room category and per
 
 | Property | Type | Contract | Description |
 | :-- | :-- | :-- | :-- |
-| `Client` | string | required | Identification of the client as described in [Authorization](../guidelines/authorization.md). |
+| `Client` | string | required | Identification of the client as described in [Authentication](../guidelines/authentication.md). |
 | `HotelId` | string | required | Unique identifier of the hotel. |
 | `StartUtc` | string | required | Start date of the reservation, i.e. arrival date. |
 | `EndUtc` | string | required | End date of the reservation, i.e. departure date. |
@@ -128,7 +128,7 @@ Get a total price for the requested reservations.
 
 | Property | Type | Contract | Description |
 | :-- | :-- | :-- | :-- |
-| `Client` | string | required | Identification of the client as described in [Authorization](../guidelines/authorization.md). |
+| `Client` | string | required | Identification of the client as described in [Authentication](../guidelines/authentication.md). |
 | `ConfigurationId` | string | required | Unique identifier of the Booking Engine configuration used. |
 | `CurrencyCode` | string | optional | ISO 4217 code of the currency in which price will be calculated. Enterprise default currency code is used as default. [Supported currency codes](../guidelines/supported-currency-codes.md)|
 | `Reservations` | array of [Reservation](#reservation) | required | List of reservations. |