imports:
  root: __package__.yml

types: 
  Order: 
    enum: 
      - asc
      - desc

  WithPage:
    properties:
      page: optional<integer>

  WithCursor:
    properties:
      cursor: optional<string>

  UserListContainer: 
    properties: 
      users: list<User>

  UserPage:
    properties:
      data: UserListContainer
      next: optional<uuid>

  UsernameContainer:
    properties:
      results: list<string>

  ListUsersExtendedResponse: 
    extends:
      - UserPage
    properties:
      total_count: 
        type: integer
        docs: The totall number of /users
 
  ListUsersPaginationResponse: 
    properties: 
      hasNextPage: optional<boolean>
      page: optional<Page>
      total_count: 
        type: integer
        docs: The totall number of /users
      data: list<User>

  Page: 
    properties: 
      page: 
        type: integer
        docs: The current page
      next: optional<NextPage>
      per_page: integer
      total_page: integer

  NextPage: 
    properties: 
      page: integer
      starting_after: string

  User: 
    properties: 
      name: string
      id: integer

service:
  auth: false
  base-path: /users
  endpoints:
    listWithCursorPagination:
      pagination: 
        cursor: $request.starting_after
        next_cursor: $response.page.next.starting_after
        results: $response.data
      method: GET
      path: ""
      request:
        name: ListUsersCursorPaginationRequest
        query-parameters:
          page: 
            type: optional<integer>
            docs: Defaults to first page
          per_page: 
            type: optional<integer>
            docs: Defaults to per page
          order: 
            type: optional<Order> 
          starting_after: 
            type: optional<string>
            docs: | 
              The cursor used for pagination in order to fetch 
              the next page of results.
      response: ListUsersPaginationResponse

    listWithBodyCursorPagination:
      pagination: 
        cursor: $request.pagination.cursor
        next_cursor: $response.page.next.starting_after
        results: $response.data
      method: POST
      path: ""
      request: 
        name: ListUsersBodyCursorPaginationRequest
        body: 
          properties:
            pagination: 
              type: optional<WithCursor>
              docs: | 
                The object that contains the cursor used for pagination
                in order to fetch the next page of results.
      response: ListUsersPaginationResponse

    listWithOffsetPagination:
      pagination: 
        offset: $request.page
        results: $response.data
      method: GET
      path: ""
      request:
        name: ListUsersOffsetPaginationRequest
        query-parameters:
          page: 
            type: optional<integer>
            docs: Defaults to first page
          per_page: 
            type: optional<integer>
            docs: Defaults to per page
          order: 
            type: optional<Order> 
          starting_after: 
            type: optional<string>
            docs: | 
              The cursor used for pagination in order to fetch 
              the next page of results.
      response: ListUsersPaginationResponse

    listWithBodyOffsetPagination:
      pagination: 
        offset: $request.pagination.page
        results: $response.data
      method: POST
      path: ""
      request: 
        name: ListUsersBodyOffsetPaginationRequest
        body: 
          properties:
            pagination: 
              type: optional<WithPage>
              docs: | 
                The object that contains the offset used for pagination
                in order to fetch the next page of results.
      response: ListUsersPaginationResponse

    listWithOffsetStepPagination:
      pagination:
        offset: $request.page
        results: $response.data
        step: $request.limit
      method: GET
      path: ""
      request:
        name: ListUsersOffsetStepPaginationRequest
        query-parameters:
          page:
            type: optional<integer>
            docs: Defaults to first page
          limit:
            type: optional<integer>
            docs: |
              The maxiumum number of elements to return.
              This is also used as the step size in this
              paginated endpoint.
          order:
            type: optional<Order>
      response: ListUsersPaginationResponse
    
    listWithOffsetPaginationHasNextPage: 
      pagination:
        offset: $request.page
        results: $response.data
        step: $request.limit
        has-next-page: $response.hasNextPage
      method: GET
      path: ""
      request:
        name: ListWithOffsetPaginationHasNextPageRequest
        query-parameters:
          page:
            type: optional<integer>
            docs: Defaults to first page
          limit:
            type: optional<integer>
            docs: |
              The maxiumum number of elements to return.
              This is also used as the step size in this
              paginated endpoint.
          order:
            type: optional<Order>
      response: ListUsersPaginationResponse

    listWithExtendedResults:
      pagination: 
        cursor: $request.cursor
        next_cursor: $response.next
        results: $response.data.users
      method: GET
      path: ""
      request:
        name: ListUsersExtendedRequest
        query-parameters:
          cursor: optional<uuid>
      response: ListUsersExtendedResponse

    listUsernames:
      pagination: 
        cursor: $request.starting_after
        next_cursor: $response.cursor.after
        results: $response.cursor.data
      method: GET
      path: ""
      request:
        name: ListUsernamesRequest
        query-parameters:
          starting_after: 
            type: optional<string>
            docs: | 
              The cursor used for pagination in order to fetch 
              the next page of results.
      response: root.UsernameCursor

    listWithGlobalConfig:
      method: GET
      path: ""
      pagination: true
      request:
        name: ListWithGlobalConfigRequest
        query-parameters:
          offset: 
            type: optional<integer>
      response: UsernameContainer