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: 'Fulltext query (<empty> = search all)'
                  required: false
                  schema:
                      type: string
                      example: 'dogs OR cats'
                      default: ''
                - name: search_type
                  in: query
                  required: false
                  schema:
                      type: integer
                      enum: [0,1]
                      default: 0
                  description: >
                       * `0` - search for records
                       * `1` - search for stories
                - 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'
    # ---------------- searchraw ----------------
    '/searchraw':
        post:
            tags:
                - searchraw
            description: >
                Fulltext search for records or stories; Returns raw es

                - pagination: use (offset/limit) OR (page/per_page)
            parameters:
                - name: query
                  in: query
                  description: 'Fulltext query (<empty> = search all)'
                  required: false
                  schema:
                      type: string
                      example: 'dogs OR cats'
                      default: ''
                - name: search_type
                  in: query
                  required: false
                  schema:
                      type: integer
                      enum: [0,1]
                      default: 0
                  description: >
                      search for records or stories
                        * `0` - search for records
                        * `1` - search for stories
                - 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
            responses:
                200:
                    description: ok
                    content:
                        application/json:
                            schema:
                                $ref: 'schemas.yaml#/ApiResponse_searchraw'
                default:
                    $ref: 'responses.yaml#/error_response'

# ------------ record -----------
    '/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'

    '/records/{base_id}':
        post:
            tags:
                - record
            summary: Creates a record
            description: |
                Creates a single record, including document and/or data.

                ### To create a record __with__ a file (document)

                _Since multipart is required to pass a file, json data must be passed as a part named "body"_

                ### To create a record __without__ file

                _Since no file is passed, data can be passed as plain body_

                ### metadata / status-bits setting

                see "PATCH" method for examples, apply only relevant "set" operation on just created record with empty 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
                            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}/setmetadatas':
        patch:
            tags:
                - record
            summary: Set or change metadata and/or status-bits of a record
            description: |
                Set or change metadata and/or status-bits of a record.

                Data is sent as json in the BODY of the request.

                * metadatas is an array of simple “actions” that are applied in the same order as defined into json.
                * field can be specified by meta_struct_id or by name
                * field value (when relevant) can be specified by meta_id or by actual value
                * method to match a value can be (strict | ignore-case | regexp); default is “ignore-case”
                * to act on multi-values we must set an “action” (set | add | delete | replace); default is “set”
                * default action “set” and special value (null, arrays) allow to write simplified actions
                * the “replace” action is useful to set/add values only if a value already exists

                # Body examples :

                ## mono-valued fields

                set a mono-value field by its meta_struct_id

                ```json
                {
                    "metadatas": [
                        {
                            "meta_struct_id": 1,
                            "action": "set",
                            "value": "A pretty string"
                        }
                    ]
                }
                ```


                same thing (because default action is “set”), by field name

                ```
                {
                    "metadatas": [
                        {
                            "field_name": "Author",
                            "value": "John Doe"
                        }
                    ]
                }
                ```

                delete a mono-valued field

                ```
                {
                    "metadatas": [
                        {
                            "field_name": "Copyright",
                            "action": "delete"
                        }
                    ]
                }
                ```

                same thing

                ```
                {
                    "metadatas": [
                        {
                            "field_name": "Copyright",
                            "value": null
                        }
                    ]
                }
                ```

                ## multi-valued

                replace a keyword __if we know its meta-id__

                ```
                {
                    "metadatas": [
                        {
                            "field_name": "Keywords",
                            "meta_id": 678,
                            "value": "Dog"
                        }
                    ]
                }
                ```

                delete a specific keyword by its meta-id (we could also set action : “delete”, omit value, …)

                ```
                {
                    "metadatas": [
                        {
                            "field_name": "Keywords",
                            "meta_id": 345,
                            "value": null
                        }
                    ]
                }
                ```

                delete a specific keyword by its value. Since we must pass the value (not null), we must set the action “delete”

                _nb_ : the default matching method is “ignore-case” so we can write the actual value all small letters

                ```
                {
                    "metadatas": [
                        {
                            "field_name": "Keywords",
                            "action": "delete",
                            "value": "doggy"
                        }
                    ]
                }
                ```

                delete __all Keywords__

                ```
                {
                    "metadatas": [
                        {
                            "field_name": "Keywords",
                            "value": null
                        }
                    ]
                }
                ```

                add a keyword

                ```
                {
                    "metadatas": [
                        {
                            "field_name": "Keywords",
                            "action": "add",
                            "value": "Cat"
                        }
                    ]
                }
                ```

                replace all keywords by new ones

                ```
                {
                    "metadatas": [
                        {
                            "field_name": "Keywords",
                            "value": null
                        },
                        {
                            "field_name": "Keywords",
                            "action": "add",
                            "value": "Cat"
                        },
                        {
                            "field_name": "Keywords",
                            "action": "add",
                            "value": "Dog"
                        }
                    ]
                }
                ```

                same thing using an array

                ```
                {
                    "metadatas": [
                        {
                            "field_name": "Keywords",
                            "value": [
                                    "Dog",
                                    "Cat",
                            ]
                        }
                    ]
                }
                ```

                simplification of multiple same actions with arrays as value

                ```
                {
                    "metadatas": [
                        {
                            "field_name": "Keywords",
                            "action": "delete",
                            "value": [
                                    "cop",
                                    "bobby",
                                    "pig",
                                    "nicks"
                            ]
                        },
                        {
                            "field_name": "Keywords",
                            "action": "add",
                            "value": [
                                    "Policeman",
                                    "Arrest"
                            ]
                        }
                    ]
                }
                ```

                replacing a keyword by value can be 2 actions if we know that the bad value exists…

                ```
                {
                    "metadatas": [
                        {
                            "field_name": "Keywords",
                            "action": "delete",
                            "value": "cop"
                        },
                        {
                            "field_name": "Keywords",
                            "action": "add",
                            "value": "Policeman"
                        }
                    ]
                }
                ```

                replace-if-exists

                …but we can also use the “replace” action if we are not sure

                ```
                {
                    "metadatas": [
                        {
                            "field_name": "Keywords",
                            "action": "replace",
                            "value": "cop",
                            "replace_with": "Policeman"
                        }
                    ]
                }
                ```

                fix  spelling errors with regexp

                ```
                {
                    "metadatas": [
                        {
                            "field_name": "Persons",
                            "action": "replace",
                            "match_method": "regexp",
                            "value": "/joh?nn?[i|y]\w+hall?[i|y]day/\w+in\w([0-9]{4})/i",
                            "replace_with": "Johnny Halliday in $1"
                        }
                    ]
                }
                ```

                add translations for existing keywords (using “replace”)

                _nb_ : multi-values are kept unique so double replacement is not a pb.

                ```
                {
                    "metadatas": [
                        {
                            "field_name": "Keywords",
                            "action": "replace",
                            "value": "dog",
                            "replace_with": [
                                    "Dog",
                                    "Chien"
                            ]
                        },
                        {
                            "field_name": "Keywords",
                            "action": "replace",
                            "value": "chien",
                            "replace_with": [
                                    "Dog",
                                    "Chien"
                            ]
                        }
                    ]
                }
                ```

                same thing using regexp

                ```
                {
                    "metadatas": [
                        {
                            "field_name": "Keywords",
                            "action": "replace",
                            "value": "/cop|bobby|pig|flic/i",
                            "match_method": "regexp",
                            "replace_with": [
                                    "Policeman",
                                    "Policier"
                            ]
                        }
                    ]
                }
                ```

                ## Status-bits

                sb can be changed with the same api.

                To not get confused with "names", sb are referenced by bit number only 4…31

                ```
                {
                    "metadatas": [
                            ...
                    ],
                    "status": [
                        {
                            "bit": 4,
                            "state": true
                        },
                        {
                            "bit": 5,
                            "state": false
                        },
                        {
                            "bit": 6,
                            "state": false
                        },
                        {
                            "bit": 7,
                            "state": false
                        }
                    ]
                }
                ```

            operationId: patchRecord
            parameters:
                - name: sbas_id
                  in: path
                  description: ID of the sbas
                  required: true
                  schema:
                      $ref: schemas.yaml#/ID
                - name: record_id
                  in: path
                  description: ID of the record
                  required: true
                  schema:
                      $ref: schemas.yaml#/ID

            requestBody:
                content:
                    application/json:
                        schema:
                            allOf:
                                - $ref: schemas.yaml#/RecordPatch
            responses:
                200:
                    description: ok
                    content:
                        application/json:
                            schema:
                                $ref: schemas.yaml#/ApiResponse_record
                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'