# NOTE: This file is auto generated by OpenAPI Generator 7.1.0 (https://openapi-generator.tech).
# Do not edit this file manually.

defmodule MBTA.Api.RoutePattern do
  @moduledoc """
  API calls for all endpoints tagged `RoutePattern`.
  """

  alias MBTA.Connection
  import MBTA.RequestBuilder

  @doc """
  List of route patterns.  Route patterns are used to describe the subsets of a route, representing different possible patterns of where trips may serve. For example, a bus route may have multiple branches, and each branch may be modeled as a separate route pattern per direction. Hierarchically, the route pattern level may be considered to be larger than the trip level and smaller than the route level.  For most MBTA modes, a route pattern will typically represent a unique set of stops that may be served on a route-trip combination. Seasonal schedule changes may result in trips within a route pattern having different routings. In simple changes, such a single bus stop removed or added between one schedule rating and the next (for example, between the Summer and Fall schedules), trips will be maintained on the same route_pattern_id. If the changes are significant, a new route_pattern_id may be introduced.  For Commuter Rail, express or skip-stop trips use the same route pattern as local trips. Some branches do have multiple route patterns when the train takes a different path. For example, `CR-Providence` has two route patterns per direction, one for the Wickford Junction branch and the other for the Stoughton branch.  

  ### Parameters

  - `connection` (MBTA.Connection): Connection to server
  - `opts` (keyword): Optional parameters
    - `:"page[offset]"` (integer()): Offset (0-based) of first element in the page
    - `:"page[limit]"` (integer()): Max number of elements to return
    - `:sort` (String.t): Results can be [sorted](http://jsonapi.org/format/#fetching-sorting) by the id or any `/data/{index}/attributes` key. Assumes ascending; may be prefixed with '-' for descending  | JSON pointer | Direction | `sort`     | |--------------|-----------|------------| | `/data/{index}/attributes/canonical` | ascending | `canonical` | | `/data/{index}/attributes/canonical` | descending | `-canonical` | | `/data/{index}/attributes/direction_id` | ascending | `direction_id` | | `/data/{index}/attributes/direction_id` | descending | `-direction_id` | | `/data/{index}/attributes/name` | ascending | `name` | | `/data/{index}/attributes/name` | descending | `-name` | | `/data/{index}/attributes/sort_order` | ascending | `sort_order` | | `/data/{index}/attributes/sort_order` | descending | `-sort_order` | | `/data/{index}/attributes/time_desc` | ascending | `time_desc` | | `/data/{index}/attributes/time_desc` | descending | `-time_desc` | | `/data/{index}/attributes/typicality` | ascending | `typicality` | | `/data/{index}/attributes/typicality` | descending | `-typicality` |  
    - `:"fields[route_pattern]"` (String.t): Fields to include with the response. Multiple fields **MUST** be a comma-separated (U+002C COMMA, \",\") list.  Note that fields can also be selected for included data types: see the [V3 API Best Practices](https://www.mbta.com/developers/v3-api/best-practices) for an example. 
    - `:include` (String.t): Relationships to include.  * `route` * `representative_trip`  The value of the include parameter **MUST** be a comma-separated (U+002C COMMA, \",\") list of relationship paths. A relationship path is a dot-separated (U+002E FULL-STOP, \".\") list of relationship names. [JSONAPI \"include\" behavior](http://jsonapi.org/format/#fetching-includes)  | include | Description | |-|-| | `route` | The route that this pattern belongs to. | | `representative_trip` | A trip that can be considered a canonical trip for the route pattern. This trip can be used to deduce a pattern's canonical set of stops and shape. |  
    - `:"filter[id]"` (String.t): Filter by multiple IDs. **MUST** be a comma-separated (U+002C COMMA, \",\") list.
    - `:"filter[route]"` (String.t): Filter by `/data/{index}/relationships/route/data/id`.  Multiple IDs **MUST** be a comma-separated (U+002C COMMA, \",\") list.   
    - `:"filter[direction_id]"` (String.t): Filter by direction of travel along the route. Must be used in conjuction with `filter[route]` to apply.  The meaning of `direction_id` varies based on the route. You can programmatically get the direction names from `/routes` `/data/{index}/attributes/direction_names` or `/routes/{id}` `/data/attributes/direction_names`.    
    - `:"filter[stop]"` (String.t): Filter by `/data/{index}/relationships/stop/data/id`.  Multiple IDs **MUST** be a comma-separated (U+002C COMMA, \",\") list.  Parent station IDs are treated as though their child stops were also included.  
    - `:"filter[canonical]"` (boolean()): Filter by canonical  true: Route pattern should be considered canonical for this route in this direction. If branching regularly occurs, this route-direction may have more than one canonical pattern. false: Route pattern should be not considered canonical for this route in this direction.   
    - `:"filter[date]"` (Date.t): Filter by date that route pattern is active The active date is the service date. Trips that begin between midnight and 3am are considered part of the previous service day. The format is ISO8601 with the template of YYYY-MM-DD.

  ### Returns

  - `{:ok, MBTA.Model.RoutePattern.t}` on success
  - `{:error, Tesla.Env.t}` on failure
  """
  @spec api_web_route_pattern_controller_index(Tesla.Env.client, keyword()) :: {:ok, MBTA.Model.RoutePattern.t} | {:ok, MBTA.Model.Forbidden.t} | {:ok, MBTA.Model.TooManyRequests.t} | {:ok, MBTA.Model.BadRequest.t} | {:error, Tesla.Env.t}
  def api_web_route_pattern_controller_index(connection, opts \\ []) do
    optional_params = %{
      :"page[offset]" => :query,
      :"page[limit]" => :query,
      :sort => :query,
      :"fields[route_pattern]" => :query,
      :include => :query,
      :"filter[id]" => :query,
      :"filter[route]" => :query,
      :"filter[direction_id]" => :query,
      :"filter[stop]" => :query,
      :"filter[canonical]" => :query,
      :"filter[date]" => :query
    }

    request =
      %{}
      |> method(:get)
      |> url("/route_patterns")
      |> add_optional_params(optional_params, opts)
      |> Enum.into([])

    connection
    |> Connection.request(request)
    |> evaluate_response([
      {429, MBTA.Model.TooManyRequests},
      {403, MBTA.Model.Forbidden},
      {400, MBTA.Model.BadRequest},
      {200, MBTA.Model.RoutePattern}
    ])
  end

  @doc """
  Show a particular route_pattern by the route's id.  Route patterns are used to describe the subsets of a route, representing different possible patterns of where trips may serve. For example, a bus route may have multiple branches, and each branch may be modeled as a separate route pattern per direction. Hierarchically, the route pattern level may be considered to be larger than the trip level and smaller than the route level.  For most MBTA modes, a route pattern will typically represent a unique set of stops that may be served on a route-trip combination. Seasonal schedule changes may result in trips within a route pattern having different routings. In simple changes, such a single bus stop removed or added between one schedule rating and the next (for example, between the Summer and Fall schedules), trips will be maintained on the same route_pattern_id. If the changes are significant, a new route_pattern_id may be introduced.  For Commuter Rail, express or skip-stop trips use the same route pattern as local trips. Some branches do have multiple route patterns when the train takes a different path. For example, `CR-Providence` has two route patterns per direction, one for the Wickford Junction branch and the other for the Stoughton branch.  

  ### Parameters

  - `connection` (MBTA.Connection): Connection to server
  - `id` (String.t): Unique identifier for route_pattern
  - `opts` (keyword): Optional parameters
    - `:"fields[route_pattern]"` (String.t): Fields to include with the response. Multiple fields **MUST** be a comma-separated (U+002C COMMA, \",\") list.  Note that fields can also be selected for included data types: see the [V3 API Best Practices](https://www.mbta.com/developers/v3-api/best-practices) for an example. 
    - `:include` (String.t): Relationships to include.  * `route` * `representative_trip`  The value of the include parameter **MUST** be a comma-separated (U+002C COMMA, \",\") list of relationship paths. A relationship path is a dot-separated (U+002E FULL-STOP, \".\") list of relationship names. [JSONAPI \"include\" behavior](http://jsonapi.org/format/#fetching-includes)  | include | Description | |-|-| | `route` | The route that this pattern belongs to. | | `representative_trip` | A trip that can be considered a canonical trip for the route pattern. This trip can be used to deduce a pattern's canonical set of stops and shape. |  

  ### Returns

  - `{:ok, MBTA.Model.RoutePattern.t}` on success
  - `{:error, Tesla.Env.t}` on failure
  """
  @spec api_web_route_pattern_controller_show(Tesla.Env.client, String.t, keyword()) :: {:ok, MBTA.Model.RoutePattern.t} | {:ok, MBTA.Model.NotAcceptable.t} | {:ok, MBTA.Model.Forbidden.t} | {:ok, MBTA.Model.TooManyRequests.t} | {:ok, MBTA.Model.NotFound.t} | {:error, Tesla.Env.t}
  def api_web_route_pattern_controller_show(connection, id, opts \\ []) do
    optional_params = %{
      :"fields[route_pattern]" => :query,
      :include => :query
    }

    request =
      %{}
      |> method(:get)
      |> url("/route_patterns/#{id}")
      |> add_optional_params(optional_params, opts)
      |> Enum.into([])

    connection
    |> Connection.request(request)
    |> evaluate_response([
      {429, MBTA.Model.TooManyRequests},
      {406, MBTA.Model.NotAcceptable},
      {404, MBTA.Model.NotFound},
      {403, MBTA.Model.Forbidden},
      {200, MBTA.Model.RoutePattern}
    ])
  end
end