Routes

The AlpineBits® standard defines a set of routes to be implemented by SERVERS following the REST architectural style for APIs. These routes commit to a well-defined pattern which is structured as follows:

• Base route: /

  The base route provides links to all versions of the AlpineBits® standard supported by the SERVER. For details, refer to Base Route.

• Version routes: /<version>

  The version route provides links to the the collections of all resource types available in the SERVER. For details, refer to Version Routes.

• Resource collection routes: /<version>/<resourceType>

  The resource collection route provides the collection of all available resources of the related type. The details for each resource collection route can be found in this chapter and its related subsection (see Resource Routes).

• Individual resource routes: /<version>/<resourceType>/<resourceId>

  The individual resource route provides the resource that is uniquely identified by that route. The details for each individual resource route can be found in this chapter and its related subsection (see Resource Routes).

• Resources' relationships routes: /<version>/<resourceType>/<resourceId>/<relationship>

  The resources' relationship route provides all resources related to the one identified in the route through the related relationship. These can be either single resources or collections of resources, depending on the definition of the relationship. The details for each resources' relationship route can be found in this chapter and its related subsection (see Resource Routes).

The definition for the fragments in the pattern above have the following interpretation:

• <version> is a code representing the version of the AlpineBits® standard implemented in that route. This allows simultaneous support to multiple standard versions, typically necessary during migration periods. Currently, the following versions can be found:

  • 2020-04: first release;

  • 2021-04: second release;

  • 2022-10: third and current release

• <resourceType> is a standard-defined resource type (e.g., events, mountainAreas, and venues). See ???.

• <resourceId>: an ID that uniquely identifies a resource that is an instance of the <resourceType>.

• <relationship>: field name of a resource’s relationship. Allows access to a resource’s related resources, such as an event’s organizer.

This chapter details all routes that are part of the AlpineBits® standard version 2022-10, listing the methods and and features that SERVERS MAY be supported by SERVERS on each of them.

Base Route

To retrieve the versions of AlpineBits® implemented by a SERVER, a CLIENT MAY send a GET request to that SERVER’s base endpoint /, as in the example below.

GET \https://example.com/ HTTP/1.1
Accept: application/vnd.api+json

A SERVER MUST respond to requests to the base endpoint / with links to each implemented versions. The data field in the response body MUST be set to null.

The following example demonstrates the response from a SERVER that has available implementations of the versions 2021-04 and 2022-10 of the AlpineBits® standard.

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{ "links": { "self": "https://example.com", "2021-04": "https://example.com/2021-04", "2022-04": "https://example.com/2022-04" }, "data": null }

SERVERS MUST support the version standard they implement on the version route dedicated to it. For example, the implementation of the AlpineBits® standard version 2022-10 MUST use the version route /2022-10 and its sub-routes.

Version Routes

To retrieve the routes implemented by a SERVER, a CLIENT MAY perform a GET request on the desired version’s endpoint (e.g., /2022-10), as in the example below.

GET \https://example.com/2022-04 HTTP/1.1
Accept: application/vnd.api+json

A SERVER MUST respond to requests to implemented version routes with links to each implemented resource collection route. The data field in the response body MUST be set to null.

The following example demonstrates the response from a SERVER that has available implementations of resource collection routes of all resource types except categories and features.

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{ "links": { "self": "https://example.com/2022-04", "agents": "https://example.com/2022-04/agents", "events": "https://example.com/2022-04/events", "eventSeries": "https://example.com/2022-04/eventSeries", "lifts": "https://example.com/2022-04/lifts", "mediaObjects": "https://example.com/2022-04/mediaObjects", "mountainAreas": "https://example.com/2022-04/mountainAreas", "skiSlopes": "https://example.com/2022-04/skiSlopes", "snowparks": "https://example.com/2022-04/snowparks", "venues": "https://example.com/2022-04/venues" }, "data": null }

Resource Routes

Resource routes are those routes that expose the resources defined in the AlpineBits® standard. This section lists all routes defined in this standard, describing what is returned as a response to a GET request, what HTTP methods the MAY respond to (see ???), and what additional features a SERVER MAY support on GET requests (see resource retrieval features).

A SERVER MUST listen to HTTP requests on all routes listed in this section. A SERVER MUST respond with a 404 Not Found status code all requests on resource routes it does not implement.

A SERVER MUST be able to provide data for at least one of the following resources routes:

• /2022-10/events

• /2022-10/mountainAreas

• /2022-10/lifts

• /2022-10/skiSlopes

• /2022-10/snowparks

Throughout the next sections' routes tables, the ^M identifies mandatory features on GET requests on related route. Other listed features that have no appended symbols are either recommended or optional for SERVERS to implement.

Agent Routes

Agent routes are those used to create, retrieve, update, and delete Agent resources, as well as to retrieve resources they are related to.

Route	Methods	Description	Additional GET features
/2022-10/agents	GET, POST	Returns a collection of all Agent resources	Pagination^M^, Sparse Fieldsets, Inclusion, Sorting, Random Sorting, Filtering, Searching
/2022-10/agents/:id	GET, PATCH, DELETE	Returns the Agent resource identified by the :id parameter	Sparse Fieldsets, Inclusion
/2022-10/agents/:id /categories	GET	Returns the collection of Category resources that classify the agent	Pagination, Sparse Fieldsets, Inclusion, Sorting, Random Sorting, Filtering, Searching
/2022-10/agents/:id /multimediaDescriptions	GET	Returns the collection of Media Object resources that are multimedia descriptions (e.g., images or videos) of the agent	Pagination, Sparse Fieldsets, Inclusion, Sorting, Random Sorting, Filtering, Searching

Category Routes

Category routes are those used to create, retrieve, update, and delete Category resources, as well as to retrieve resources they are related to.

Route	Methods	Description	Additional GET features
/2022-10/categories	GET, POST	Returns the collection of all Category resources	Pagination^M^, Sparse Fieldsets, Inclusion, Sorting, Random Sorting, Filtering, Searching
/2022-10/categories/:id	GET, PATCH, DELETE	Returns the Category resource identified by the id parameter	Sparse Fieldsets, Inclusion
/2022-10/categories/:id /children	GET	Returns the collection of Category resources that are children of the category	Pagination, Sparse Fieldsets, Inclusion, Sorting, Random Sorting, Filtering, Searching
/2022-10/categories/:id /multimediaDescriptions	GET	Returns the collection of Media Object resources that are multimedia descriptions (e.g., images or videos) of the category	Pagination, Sparse Fieldsets, Inclusion, Sorting, Random Sorting, Filtering, Searching
/2022-10/categories/:id /parents	GET	Returns the collection of Category resources that are parents of the category	Pagination, Sparse Fieldsets, Inclusion, Sorting, Random Sorting, Filtering, Searching

Event Routes

Event routes are those used to create, retrieve, update, and delete Event resource, as well as to retrieve resources they are related to. \

Route	Methods	Description	Additional GET features
/2022-10/events	GET, POST	Returns the collection of all Event resources	Pagination^M^, Sparse Fieldsets, Inclusion, Sorting, Random Sorting, Filtering, Searching
/2022-10/events/:id	GET, PATCH, DELETE	Returns the Event resource identified by the id parameter	Sparse Fieldsets, Inclusion
/2022-10/events/:id /categories	GET	Returns the collection of Category resources that classify the event	Pagination, Sparse Fieldsets, Inclusion, Sorting, Random Sorting, Filtering, Searching
/2022-10/events/:id /contributors	GET	Returns the collection of Agent resources that are contributors on the event	Pagination, Sparse Fieldsets, Inclusion, Sorting, Random Sorting, Filtering, Searching
/2022-10/events/:id /multimediaDescriptions	GET	Returns the collection of Media Object resources that are multimedia descriptions (e.g., images or videos) of the event	Pagination, Sparse Fieldsets, Inclusion, Sorting, Random Sorting, Filtering, Searching
/2022-10/events/:id /organizers	GET	Returns the collection of Agent resources that are organizers of the event	Pagination, Sparse Fieldsets, Inclusion, Sorting, Random Sorting, Filtering, Searching
/2022-10/events/:id /publisher	GET	Return the Agent resource that is the publisher of the event	Sparse Fieldsets, Inclusion
/2022-10/events/:id /series	GET	Return the Event Series resource that the event is an edition of	Sparse Fieldsets, Inclusion
/2022-10/events/:id /sponsors	GET	Returns the collection of Agent resources that are sponsors of the event	Pagination, Sparse Fieldsets, Inclusion, Sorting, Random Sorting, Filtering, Searching
/2022-10/events/:id /subEvents	GET	Returns the collection of Event resources that are part of the event	Pagination, Sparse Fieldsets, Inclusion, Sorting, Random Sorting, Filtering, Searching
/2022-10/events/:id /venues	GET	Returns the collection of Venue resources where the event will happen	Pagination, Sparse Fieldsets, Inclusion, Sorting, Random Sorting, Filtering, Searching

Event Series Routes

Event Series routes are those used to create, retrieve, update, and delete Event Series resources, as well as to retrieve resources they are related to.

Route	Methods	Description	Additional GET features
/2022-10/eventSeries	GET, POST	Returns the collection of all Event Series resources	Pagination^M^, Sparse Fieldsets, Inclusion, Sorting, Random Sorting, Filtering, Searching
/2022-10/eventSeries/:id	GET, PATCH, DELETE	Returns the Event Series resource identified by the id parameter	Sparse Fieldsets, Inclusion
/2022-10/eventSeries/:id /categories	GET	Returns the collection of Category resources that classify the event series	Pagination, Sparse Fieldsets, Inclusion, Sorting, Random Sorting, Filtering, Searching
/2022-10/eventSeries/:id /editions	GET	Returns the collection of Event resources that are editions of the event series	Pagination, Sparse Fieldsets, Inclusion, Sorting, Random Sorting, Filtering, Searching
/2022-10/eventSeries/:id /multimediaDescriptions	GET	Returns the collection of Media Object resources that are multimedia descriptions (e.g., images or videos) of the event series	Pagination, Sparse Fieldsets, Inclusion, Sorting, Random Sorting, Filtering, Searching

Feature Routes

Feature routes are those used to create, retrieve, update, and delete Feature resources, as well as to retrieve resources they are related to.

Route	Methods	Description	Additional GET features
/2022-10/features	GET, POST	Returns the collection of all Feature resources	Pagination^M^, Sparse Fieldsets, Inclusion, Sorting, Random Sorting, Filtering, Searching
/2022-10/features/:id	GET, PATCH, DELETE	Returns the Feature resource identified by the id parameter	Sparse Fieldsets, Inclusion
/2022-10/features/:id /children	GET	Returns the collection of Feature resources that are children of the feature	Pagination, Sparse Fieldsets, Inclusion, Sorting, Random Sorting, Filtering, Searching
/2022-10/features/:id /multimediaDescriptions	GET	Returns the collection of Media Object resources that are multimedia descriptions (e.g., images or videos) of the feature	Pagination, Sparse Fieldsets, Inclusion, Sorting, Random Sorting, Filtering, Searching
/2022-10/features/:id /parents	GET	Returns the collection of Feature resources that are parents of the feature	Pagination, Sparse Fieldsets, Inclusion, Sorting, Random Sorting, Filtering, Searching

Lift Routes

Lift routes are those used to create, retrieve, update, and delete Lift resources, as well as to retrieve resources they are related to.

Route	Methods	Description	Additional GET features
/2022-10/lifts	GET, POST	Returns the collection of all Lift resources	Pagination^M^, Sparse Fieldsets, Inclusion, Sorting, Random Sorting, Filtering, Searching
/2022-10/lifts/:id	GET, PATCH, DELETE	Returns the Lift resource identified by the id parameter	Sparse Fieldsets, Inclusion
/2022-10/lifts/:id /categories	GET	Returns the collection of Category resources that classify the lift	Pagination, Sparse Fieldsets, Inclusion, Sorting, Random Sorting, Filtering, Searching
/2022-10/lifts/:id /connections	GET	Returns the collection of Lift, Mountain Area, Ski Slope, and Snowpark resources that are physically accessible from the lift	Pagination, Sparse Fieldsets, Inclusion, Sorting, Random Sorting, Filtering, Searching
/2022-10/lifts/:id /multimediaDescriptions	GET	Returns the collection of Media Object resources that are multimedia descriptions (e.g., images or videos) of the lift	Pagination, Sparse Fieldsets, Inclusion, Sorting, Random Sorting, Filtering, Searching

Media Object Routes

Media Object routes are those used to create, retrieve, update, and delete Media Object resources, as well as to retrieve resources they are related to.

Route	Methods	Description	Additional GET features
/2022-10/mediaObjects	GET, POST	Returns the collection of all Media Object resources	Pagination^M^, Sparse Fieldsets, Inclusion, Sorting, Random Sorting, Filtering, Searching
/2022-10/mediaObjects/:id	GET, PATCH, DELETE	Returns the Media Object resource identified by the id parameter	Sparse Fieldsets, Inclusion
/2022-10/mediaObjects/:id /categories	GET	Returns the collection of Category resources that classify the media object	Pagination, Sparse Fieldsets, Inclusion, Sorting, Random Sorting, Filtering, Searching
/2022-10/mediaObjects/:id /licenseHolder	GET	Return the Agent resource that is the license holder of the media object	Sparse Fieldsets, Inclusion

Mountain Area Routes

Mountain Area routes are those used to create, retrieve, update, and delete Mountain Area resources, as well as to retrieve resources they are related to.

Route	Methods	Description	Additional GET features
/2022-10/mountainAreas	GET, POST	Returns the collection of all Mountain Area resources	Pagination^M^, Sparse Fieldsets, Inclusion, Sorting, Random Sorting, Filtering, Searching
/2022-10/mountainAreas/:id	GET, PATCH, DELETE	Returns the Mountain Area resource identified by the id parameter	Sparse Fieldsets, Inclusion
/2022-10/mountainAreas/:id /areaOwner	GET	Return the Agent resource that is the owner of the mountain area	Sparse Fieldsets, Inclusion
/2022-10/mountainAreas/:id /categories	GET	Returns the collection of Category resources that classify the mountain area	Pagination, Sparse Fieldsets, Inclusion, Sorting, Random Sorting, Filtering, Searching
/2022-10/mountainAreas/:id /connections	GET	Returns the collection of Lift, Mountain Area, Ski Slope, and Snowpark resources that are physically accessible from the mountain area	Pagination, Sparse Fieldsets, Inclusion, Sorting, Random Sorting, Filtering, Searching
/2022-10/mountainAreas/:id /lifts	GET	Returns the collection of Lift resources that are located within the mountain area	Pagination, Sparse Fieldsets, Inclusion, Sorting, Random Sorting, Filtering, Searching
/2022-10/mountainAreas/:id /multimediaDescriptions	GET	Returns the collection of Media Object resources that are multimedia descriptions (e.g., images or videos) of the mountain area	Pagination, Sparse Fieldsets, Inclusion, Sorting, Random Sorting, Filtering, Searching
/2022-10/mountainAreas/:id /skiSlopes	GET	Returns the collection of Ski Slope resources that are located within the mountain area	Pagination, Sparse Fieldsets, Inclusion, Sorting, Random Sorting, Filtering, Searching
/2022-10/mountainAreas/:id /snowparks	GET	Returns the collection of Snowpark resources that are located within the mountain area	Pagination, Sparse Fieldsets, Inclusion, Sorting, Random Sorting, Filtering, Searching
/2022-10/mountainAreas/:id /subAreas	GET	Returns the collection of Mountain Area resources that are located within the mountain area	Pagination, Sparse Fieldsets, Inclusion, Sorting, Random Sorting, Filtering, Searching

Ski Slope Routes

Ski Slope routes are those used to create, retrieve, update, and delete Ski Slope resources, as well as to retrieve resources they are related to.

Route	Methods	Description	Additional GET features
/2022-10/skiSlopes	GET, POST	Returns the collection of all Ski Slope resources	Pagination^M^, Sparse Fieldsets, Inclusion, Sorting, Random Sorting, Filtering, Searching
/2022-10/skiSlopes/:id	GET, PATCH, DELETE	Returns the Ski Slope resource identified by the id parameter	Sparse Fieldsets, Inclusion
/2022-10/skiSlopes/:id /categories	GET	Returns the collection of Category resources that classify the ski slope	Pagination, Sparse Fieldsets, Inclusion, Sorting, Random Sorting, Filtering, Searching
/2022-10/skiSlopes/:id /connections	GET	Returns the collection of Lift, Mountain Area, Ski Slope, and Snowpark resources that are physically accessible from the ski slope	Pagination, Sparse Fieldsets, Inclusion, Sorting, Random Sorting, Filtering, Searching
/2022-10/skiSlopes/:id /multimediaDescriptions	GET	Returns the collection of Media Object resources that are multimedia descriptions (e.g., images or videos) of the ski slope	Pagination, Sparse Fieldsets, Inclusion, Sorting, Random Sorting, Filtering, Searching

Snowpark Routes

Snowpark routes are those used to create, retrieve, update, and delete Snowpark resources, as well as to retrieve resources they are related to.

Route	Methods	Description	Additional GET features
/2022-10/snowparks	GET, POST	Returns the collection of all Snowpark resources	Pagination^M^, Sparse Fieldsets, Inclusion, Sorting, Random Sorting, Filtering, Searching
/2022-10/snowparks/:id	GET, PATCH, DELETE	Returns the Snowpark resource identified by the id parameter	Sparse Fieldsets, Inclusion
/2022-10/snowparks/:id /categories	GET	Returns the collection of Category resources that classify the snowpark	Pagination, Sparse Fieldsets, Inclusion, Sorting, Random Sorting, Filtering, Searching
/2022-10/snowparks/:id /connections	GET	Returns the collection of Lift, Mountain Area, Ski Slope, and Snowpark resources that are physically accessible from the snowpark	Pagination, Sparse Fieldsets, Inclusion, Sorting, Random Sorting, Filtering, Searching
/2022-10/snowparks/:id /features	GET	Returns the collection of Feature resources that are present in the snowpark	Pagination, Sparse Fieldsets, Inclusion, Sorting, Random Sorting, Filtering, Searching
/2022-10/snowparks/:id /multimediaDescriptions	GET	Returns the collection of Media Object resources that are multimedia descriptions (e.g., images or videos) of the snowpark	Pagination, Sparse Fieldsets, Inclusion, Sorting, Random Sorting, Filtering, Searching

Venue Routes

Venue routes are those used to create, retrieve, update, and delete Venue resources, as well as to retrieve resources they are related to.

Route	Methods	Description	Additional GET features
/2022-10/venues	GET, POST	Returns the collection of all Venue resources	Pagination^M^, Sparse Fieldsets, Inclusion, Sorting, Random Sorting, Filtering, Searching
/2022-10/venues/:id	GET, PATCH, DELETE	Returns the Venue resource identified by the id parameter	Sparse Fieldsets, Inclusion
/2022-10/venues/:id /categories	GET	Returns the collection of Category resources that classify the venue	Pagination, Sparse Fieldsets, Inclusion, Sorting, Random Sorting, Filtering, Searching
/2022-10/venues/:id /multimediaDescriptions	GET	Returns the collection of Media Object resources that are multimedia descriptions (e.g., images or videos) of the venue	Pagination, Sparse Fieldsets, Inclusion, Sorting, Random Sorting, Filtering, Searching