openapi: 3.0.0
info:
    description: >
        This is the documentation of Phraseanet API (v3)
#        [https://alpha.preprod.alchemyasp.com/api/v3](https://alpha.preprod.alchemyasp.com/api/v3).
    version: "1.0.0-oas3"
    title: Phraseanet API
    # todo : fix url
    termsOfService: 'http://phraseanet.com/terms/'
    contact:
        email: support@alchemy.fr
    license:
        name: GNU GPL V3
        url: 'https://www.gnu.org/licenses/gpl-3.0.en.html'
#servers:
#    - url: https://alpha.preprod.alchemyasp.com/api/v3
#      description: Phraseanet alpha (dev)
#    - url: https://beta.preprod.alchemyasp.com/api/v3
#      description: Phraseanet beta
#security:
#    - api_key: []
#    - oAuth2Password: []
components:
#    securitySchemes:
#        api_key:
#            type: apiKey
#            name: oauth_token
#            in: query
#        oAuth2Password:
#            type: oauth2
#            description: This API uses OAuth 2 with the password grant flow. [More info](https://api.example.com/docs/auth)
#            flows:
#                password:   # <-- OAuth flow(authorizationCode, implicit, password or clientCredentials)
#                    tokenUrl: azea
    parameters:
        offsetParam:
            name: offset
            in: query
            description: offset in records count
            required: false
            schema:
                type: integer
                minimum: 0
                default: 0
        limitParam:
            name: limit
            in: query
            description: number of results
            required: false
            schema:
                type: integer
                minimum: 1
                maximum: 100
                default: 10
        sbas_id:
            name: sbas_id
            in: path
            description: ID of the databox
            required: true
            schema:
                $ref: schemas.yaml#/ID
        record_id:
            name: record_id
            in: path
            description: ID of the record
            required: true
            schema:
                $ref: schemas.yaml#/ID
paths:
    '/me':
        get:
            description: 'blabla'
            servers:
                - url: 'https://alpha.preprod.alchemyasp.com/api/v1'
            responses:
                200:
                    description: successful operation
                default:
                    description: Any error

# ---------------- search ----------------
    '/search':
        post:
            tags:
                - search
            description: |
                Fulltext search for records or stories.

                - pagination: use (offset/limit) OR (page/per_page)
            parameters:
                - name: query
                  in: query
                  description: 'The fulltext query (<empty> = search all)'
                  required: false
                  schema:
                      type: string
                      example: 'dogs OR cats'
                      default: ''
                - name: search_type
                  in: query
                  description: 0 to search for records ; 1 to search for stories
                  required: false
                  schema:
                      type: integer
                      enum:
                          - 0
                          - 1
                      default: 0
                - name: page
                  in: query
                  description: page number, from 1. Use along with "per_page"
                  required: false
                  schema:
                      type: integer
                      minimum: 1
                      default: 1
                - name: per_page
                  in: query
                  description: number of results per page. Use along with "page"
                  required: false
                  schema:
                      type: integer
                      minimum: 1
                      maximum: 100
                      default: 10
                - name: offset
                  in: query
                  description: offset in records count, from 0. Use along with "limit"
                  required: false
                  schema:
                      type: integer
                      minimum: 0
                      # default: 0
                - name: limit
                  in: query
                  description: number of results. Use along with "offset"
                  required: false
                  schema:
                      type: integer
                      minimum: 1
                      maximum: 100
                      # default: 10
                - name: story_children_limit
                  in: query
                  description: For each story in result, include N children
                  required: false
                  schema:
                      type: integer
                      minimum: 0
                      maximum: 10
                      default: '0'
                - name: include
                  in: query
                  description: Suplemental elements to be included in response
                  required: false
                  schema:
                      type: array
                      uniqueItems: false
                      items:
                          type: string
                          enum:
                              - facets
                              - result.stories.children
            responses:
                200:
                    description: ok
                    content:
                        application/json:
                            schema:
                                $ref: 'schemas.yaml#/ApiResponse_search'
                default:
                    $ref: 'responses.yaml#/error_response'

# ------------ record -----------
    '/records/{base_id}':
        post:
            tags:
                - record
            summary: Creates a record
            description: 'Creates a single record, including document and/or data.'
            operationId: createRecord
            parameters:
                - name: base_id
                  in: path
                  description: ID of the base
                  required: true
                  schema:
                      $ref: schemas.yaml#/ID
            requestBody:
                content:
                    multipart/form-data:
                        schema:
                            description: 'to create a record with a file (document)'
                            type: object
                            properties:
                                body:
                                    $ref: schemas.yaml#/RecordPatch
                                file:
                                    description : 'uploaded file'
                                    type: string
                                    format: binary
                    application/json:
                        schema:
                            description: 'to create a record without file (document)'
                            allOf:
                                - $ref: schemas.yaml#/RecordPatch
            responses:
                200:
                    description: ok
                    content:
                        application/json:
                            schema:
                                $ref: schemas.yaml#/ApiResponse_record
                default:
                    $ref: 'responses.yaml#/error_response'
#            security:
#                - api_key: []
    '/records/{sbas_id}/{record_id}':
        get:
            tags:
                - record
            summary: Find record by sbas_id and record_id
            description: Returns a single record
            operationId: getRecordById
            parameters:
                - $ref: '#/components/parameters/sbas_id'
                - $ref: '#/components/parameters/record_id'
            responses:
                200:
                    description: ok
                    content:
                        application/json:
                            schema:
                                $ref: schemas.yaml#/ApiResponse_record
                404:
                    description: Record not found
                default:
                    $ref: 'responses.yaml#/error_response'
    '/stories/{sbas_id}/{record_id}/children':
        get:
            tags:
                - story
            summary: Returns uri of each record (child) contained in the story ; Optional pagination
            description: Returns children of a story
            operationId: getStoryChildren
            parameters:
                - $ref: '#/components/parameters/sbas_id'
                - $ref: '#/components/parameters/record_id'
                - name: page
                  in: query
                  description: page number (default 1)
                  required: false
                  schema:
                      type: integer
                - name: per_page
                  in: query
                  description: number of children (records uri) per page (default 10)
                  required: false
                  schema:
                      type: integer
            responses:
                200:
                    description: ok
                    content:
                        application/json:
                            schema:
                                $ref: schemas.yaml#/ApiResponse_RecordsUriArray
                404:
                    description: Story (record) not found
                default:
                    $ref: 'responses.yaml#/error_response'