There are 4 basic patterns we will use for our API, to provide a consistent experience across all capabilities:

Search pattern

Many use cases require the retrieval of one or more specific records that have to be searched for and retrieved before the use case can be completed. For doing these types of searches, you should use query string parameters. They should be passed into the base URL of the endpoint you are calling. For instance, to search for guests, you would do a GET on /guests and provide your search criteria.

Because these types of searches are often very flexible, it’s not uncommon for all of the parameters to be optional. In this case, you would need to read the documentation to get more information about which parameters can be used together. These are some of the parameters that are accepted by the Guest Service’s GET operation:

• cardCode
• cardNumber
• city
• country
• emailAddress
• firstName
• honorsNumber
• lastName
• phoneNumber
• postalCode
• qualifiedNameSearch
• state

If searching using honorsNumber, that parameter may be the only one provided. On the other hand, if you provide lastName and firstName, and qualifiedNameSearch is ‘true’, you must provide other parameters too, such as emailAddress, cardCode, cardNumber, etc. This is an example of a guest search request:

/guests?emailAddress=someone@business.com&state=MA&city=Boston&lastName=Smith&firstName=John&qualifiedNameSearch=true

Data access pattern

For direct data access, pass in the unique ID of the item in order to retrieve all of the data for a specific record. The format of the ID will depend on the specific type of data being accessed. For properties, the ‘propCode’ is the ID, to retrieve a reservation, ‘confNumber’ is used. Some examples are:

• /props/DCAOT which would give basic details about the Hilton Alexandria Old Town.
• /reservations/9999999 which would give basic details about a specific reservation.

And it is also possible to access more detailed information:

• /props/DCAOT/rateplans would return the list of rateplans, including each rateplan’s summary attributes, for property DCAOT.
• /props/DCAOT/rateplans/RP001/restrictions would return the list of rateplan restrictions for rateplan RP001 at property DCAOT.

Business Process Pattern

Business processes can be performed on certain entities. A business process URL will end with the process name preceded by the primary business object that is being acted upon. For instance, if we consider the ‘check-in’ business process, it can be achieved by appending the business process name to the end of the stay URL. This business process will result in further actions that the client may not even be aware of: during the completion of the checkin process, the room status will change, the status of the stay will become ‘inHouse’, the room number will be updated on the stay record, the digital key resource might need to be updated, etc. An example of a business process is doing a POST to this endpoint:

/stays/12345/checkin

Experience Patterns

The experience of the API can be customized by using the ‘fields’ parameter. This is a platform-wide capability. It is available on every GET request.

By passing in ‘?fields=param1,param2’, etc., the fields returned by the service can be limited to only those that are needed. Keep in mind that the fields you need may be embedded in other structures. If you want to retrieve a guest’s first and last name, the GET request could look like this (firstName and lastName are part of other data structures in the response):

/guests/12345?fields=personalinfo.name.firstName,personalinfo.name.lastName

As a consumer of the service, this allows you to tune the response to only the attributes you require. The example above would retrieve only the first and last name attributes from the guest that is being queried.