openapi.yaml

openapi: 3.0.0
info:
  version: 1.0.0
  title: A Scraper
  description: |
    This defines how a scraper should behave.

    ## Auth

    The basic auth authentication username and password can be obtained via RT-CV.
    Within RT-CV select the scraper you want the credentials of and copy the `Key ID` and the `Key` itself.
    Now you can use the `Key ID` as username and `Key` as password

    Most server side HTTP clients allow basic auth credentials within the url so making requests to a scraper is as easy as:
    ```sh
    # Make sure to replace the username and password with RT-CV scraper's key key id and key
    curl https://aaaaaaaaaaaaaaaaaaaaaaaa:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa@werk-scraper.fly.dev/health
    ```
servers:
  - url: https://werk-scraper.fly.dev
  - url: https://ikbenbeschikbaar-scraper.fly.dev
  - url: https://debanensite-scraper.fly.dev
  - url: https://techniekwerkt-scraper.fly.dev
  - url: https://f2f-linkedin-scraper.fly.dev
security:
  - basicAuth: []
paths:
  /health:
    get:
      description: Used by other services to check if a scraper is alive
      responses:
        200:
          description: The scraper is functioning as expected.
          content:
            application/json:
              schema:
                type: object
                required:
                  - status
                  - lastSentCv
                properties:
                  status:
                    type: boolean
                    const: true
                  lastSentCv:
                    description: iso timestamp with time of last send cv if it has been send
                    type: string
                    format: date-time
                    nullable: true
        500:
          description: The scraper is malfunctioning, see the returned errors for more information
          content:
            application/json:
              schema:
                type: object
                required:
                  - status
                  - lastSentCv
                  - errors
                properties:
                  status:
                    type: boolean
                    const: false
                  lastSentCv:
                    description: iso timestamp with time of last send cv if it has been send
                    type: string
                    format: date-time
                    nullable: true
                  errors:
                    description: List of errors if status is false.
                    type: array
                    items:
                      type: string
        401:
          $ref: "#/components/responses/UnauthorizedError"
  /cv:
    post:
      description: Get a single CV by its reference number
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - referenceNr
              properties:
                referenceNr:
                  type: string
                  minLength: 1
      responses:
        200:
          description: The CV
          content:
            application/json:
              schema:
                type: object
                required:
                  - cv
                properties:
                  cv:
                    description: Contains the cv in the, the format of the cv is described by the RT-CV server https://bitbucket.org/teamscript/rt-cv/src/main/models/cv.go#lines-18
                    type: object
                  hasDocument:
                    description: Indicates if this cv has a cv document attached and the cv mata mostly likely is minimal
                    type: boolean
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/UnauthorizedError"
        404:
          $ref: "#/components/responses/NotImplemented"
        500:
          $ref: "#/components/responses/InternalServerError"
  /cv-document:
    post:
      description: Get a CV Document by its reference number,
        you can check if a cv has a document by using the /cv endpoint
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - referenceNr
              properties:
                referenceNr:
                  type: string
                  minLength: 1
      responses:
        200:
          description: The CV document
          headers:
            Content-Type:
              description: The document mimetype of the cv document
              schema:
                type: string
            Filename:
              description: The filename of the cv document
              schema:
                type: string
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/UnauthorizedError"
        404:
          $ref: "#/components/responses/NotImplemented"
        500:
          $ref: "#/components/responses/InternalServerError"
  /check-credentials:
    post:
      description: Check if given credentials are correct
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - username
                - password
              properties:
                username:
                  type: string
                  minLength: 1
                password:
                  type: string
                  minLength: 1
      responses:
        200:
          description: The given credentials where checked correctly
          content:
            application/json:
              schema:
                type: object
                required:
                  - valid
                properties:
                  valid:
                    type: boolean
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/UnauthorizedError"
        404:
          $ref: "#/components/responses/NotImplemented"
        500:
          $ref: "#/components/responses/InternalServerError"
  /check-site-storage-credentials:
    post:
      description: Check if given credentials are correct
      requestBody:
        required: true
        content:
          application/json:
            schema:
              description: The credentials to check.
              type: object
              properties:
                cookies:
                  description: if the site uses cookies for authentication. The key is the cookie name and the value is the cookie value
                  type: object
                  additionalProperties:
                    type: array
                    items:
                      type: string
      responses:
        200:
          description: The given credentials where checked correctly
          content:
            application/json:
              schema:
                type: object
                required:
                  - valid
                properties:
                  valid:
                    type: boolean
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/UnauthorizedError"
        404:
          $ref: "#/components/responses/NotImplemented"
        500:
          $ref: "#/components/responses/InternalServerError"
components:
  securitySchemes:
    basicAuth:
      description: Authenticate using the same credentials as the credentials in RTCV_SERVER
      type: http
      scheme: basic
  schemas:
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
  responses:
    UnauthorizedError:
      description: Basic authentication missing or invalid
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    NotImplemented:
      description: Not implemented
      headers:
        X-Not-Implemented:
          schema:
            type: boolean
            default: true
          description: "A header that indicates that this method is not implemented"
      content:
        application/json:
          schema:
            type: object
            required:
              - error
            properties:
              error:
                type: string
                default: "Not Implemented"
    InternalServerError:
      description: Internal server error, something within the scraper went wrong that is un related to the provided login credentials thus the given login credentials might be valid or invalid this is just a server failure.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    BadRequest:
      description: Bad request, this is most likely returned when the body is invalid
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"