ecmwf-dataset-crawl/controller/swagger.yaml

---
swagger: "2.0"
info:
  description: "Definition of the Frontfacing API of the controller component for\
    \ ecmwf-dataset-crawl. This API is requires no authentication. If required, add\
    \ a proxy for that."
  version: "0.1.0"
  title: "ecmwf-dataset-crawl API"
  license:
    name: "Apache 2.0"
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"
host: "localhost:9000"
basePath: "/"
tags:
- name: "crawls"
  description: "Crawl Metadata"
- name: "results"
  description: "Crawl Results"
schemes:
- "http"
paths:
  /crawls:
    get:
      tags:
      - "crawls"
      summary: "Get all Crawls"
      operationId: "getCrawls"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters: []
      responses:
        200:
          description: "Success"
          schema:
            type: "array"
            items:
              $ref: "./schema.json#/definitions/CrawlResponse"
        500:
          description: "Internal Error"
      x-swagger-router-controller: "Crawls"
    put:
      tags:
      - "crawls"
      summary: "Add a new Crawl"
      operationId: "addCrawl"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - in: "body"
        name: "crawl"
        required: true
        schema:
          $ref: "./schema.json#/definitions/CrawlRequest"
      responses:
        201:
          description: "Created"
          schema:
            $ref: "./schema.json#/definitions/CrawlResponse"
        400:
          description: "Bad Request"
        500:
          description: "Internal Error"
      x-swagger-router-controller: "Crawls"
    options:
      tags:
      - "crawls"
      summary: "Only defined to handle preflight CORS requests"
      operationId: "handlePreflight"
      parameters: []
      responses:
        200:
          description: "Success"
      x-swagger-router-controller: "Crawls"
  /crawls/{crawlid}:
    get:
      tags:
      - "crawls"
      summary: "Get a Crawl"
      operationId: "getCrawl"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - name: "crawlid"
        in: "path"
        description: "Crawl ID to operate on"
        required: true
        type: "string"
      responses:
        200:
          description: "Success"
          schema:
            $ref: "./schema.json#/definitions/CrawlResponse"
        404:
          description: "Crawl not found"
        500:
          description: "Internal Error"
      x-swagger-router-controller: "Crawls"
    delete:
      tags:
      - "crawls"
      summary: "Stop a Crawl"
      operationId: "stopCrawl"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - name: "crawlid"
        in: "path"
        description: "Crawl ID to operate on"
        required: true
        type: "string"
      responses:
        200:
          description: "Success"
        500:
          description: "Internal Error"
      x-swagger-router-controller: "Crawls"
    options:
      tags:
      - "crawls"
      summary: "Only defined to handle preflight CORS requests"
      operationId: "handlePreflight2"
      parameters:
      - name: "crawlid"
        in: "path"
        description: "Crawl ID to operate on"
        required: true
        type: "string"
      responses:
        200:
          description: "Success"
      x-swagger-router-controller: "Crawls"
  /results:
    get:
      tags:
      - "results"
      summary: "Get crawl results with optional filtering"
      description: ""
      operationId: "getResults"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - name: "crawls"
        in: "query"
        description: "Crawl IDs to filter results"
        required: false
        type: "string"
      - name: "query"
        in: "query"
        description: "Elastic Search query term to filter results"
        required: false
        type: "string"
      - name: "onlyCrawlLanguages"
        in: "query"
        description: "Only return results in the original languages of the associated crawl"
        required: false
        type: "boolean"
        default: false
      - name: "size"
        in: "query"
        description: "The amount of results to return"
        required: false
        type: "integer"
        default: 25
      - name: "from"
        in: "query"
        description: "First result to return (pagination)"
        required: false
        type: "integer"
        default: 0
      - name: "format"
        in: "query"
        description: "Format in which results are returned"
        required: false
        type: "string"
        enum:
        - "csv"
      - name: "download"
        in: "query"
        description: "Whether to send an attachment header"
        required: false
        type: "boolean"
      responses:
        200:
          description: "Success"
          schema:
            type: "array"
            items:
              $ref: "#/definitions/Site"
        500:
          description: "Internal Error"
      externalDocs:
        description: "Query parameter from Elastic Search"
        url: "https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html"
      x-swagger-router-controller: "Results"
    delete:
      tags:
      - "results"
      summary: "Deletes crawl results based on filter"
      description: ""
      operationId: "deleteResults"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - name: "crawls"
        in: "query"
        description: "Crawl IDs to filter results"
        required: false
        type: "string"
      - name: "query"
        in: "query"
        description: "Elastic Search query term to filter results"
        required: false
        type: "string"
      responses:
        200:
          description: "Success"
          schema:
            $ref: "#/definitions/DeleteResponse"
        500:
          description: "Internal Error"
      externalDocs:
        description: "Query parameter from Elastic Search"
        url: "https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html"
      x-swagger-router-controller: "Results"
    options:
      tags:
      - "results"
      summary: "Only defined to handle preflight CORS requests"
      operationId: "handlePreflight3"
      parameters: []
      responses:
        200:
          description: "Success"
      x-swagger-router-controller: "Results"
  /results/classify:
    post:
      tags:
      - "results"
      summary: "Manually classify one or more results"
      description: ""
      operationId: "classifyResults"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - name: "classifyRequest"
        in: "body"
        schema:
          type: "object"
          required:
          - "urls"
          - "label"
          properties:
            urls:
              description: "URLs to classify"
              type: "array"
              items:
                type: "string"
            label:
              description: "The class to assign to the URLs"
              type: "string"
              enum:
              - "dataset"
              - "related"
              - "unrelated"
      responses:
        200:
          description: "Success"
          schema:
            type: "integer"
        500:
          description: "Internal Error"
      x-swagger-router-controller: "Results"
    options:
      tags:
      - "results"
      summary: "Only defined to handle preflight CORS requests"
      operationId: "handlePreflight3"
      parameters: []
      responses:
        200:
          description: "Success"
      x-swagger-router-controller: "Results"

  /results/counts:
    get:
      tags:
      - "results"
      summary: "Get count of crawl results with optional filtering"
      description: ""
      operationId: "getResultCount"
      produces:
      - "application/json"
      parameters:
      - name: "crawls"
        in: "query"
        description: "Crawl IDs to filter results"
        required: false
        type: "string"
      - name: "query"
        in: "query"
        description: "Elastic Search query term to filter results"
        required: false
        type: "string"
      responses:
        200:
          description: "Success"
          schema:
            type: "integer"
        500:
          description: "Internal Error"
      externalDocs:
        description: "Query parameter from Elastic Search"
        url: "https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html"
      x-swagger-router-controller: "Results"
  /capabilities/languages:
    get:
      tags:
      - "capabilities"
      summary: "Returns all available language codes for translation"
      operationId: "getLanguages"
      produces:
      - "application/json"
      parameters: []
      responses:
        200:
          description: "Success"
          schema:
            type: "array"
            items:
              type: "object"
        500:
          description: "Internal Error"
      x-swagger-router-controller: "Capabilities"
  /capabilities/countries:
    get:
      tags:
      - "capabilities"
      summary: "Returns all available country codes for translation"
      operationId: "getCountries"
      produces:
      - "application/json"
      parameters: []
      responses:
        200:
          description: "Success"
          schema:
            type: "array"
            items:
              type: "object"
        500:
          description: "Internal Error"
      x-swagger-router-controller: "Capabilities"
definitions:
  Site:
    properties:
      crawl:
        type: "string"
        format: "uuid"
      title:
        type: "string"
      url:
        type: "string"
      scores:
        $ref: "#/definitions/Site_scores"
      metadata:
        $ref: "#/definitions/Site_metadata"
    example:
      metadata:
        contact: "contact"
      scores:
        dataportal: 6.02745618307040320615897144307382404804229736328125
        dataset: 0.80082819046101150206595775671303272247314453125
      url: "https://example.com/foobar"
      crawl: "046b6c7f-0b8a-43b9-b35d-6489e6daee91"
  DeleteResponse:
    properties:
      deleted:
        type: "integer"
    example:
      deleted: 0
  Site_scores:
    properties:
      dataset:
        type: "number"
      dataportal:
        type: "number"
    example:
      dataportal: 6.02745618307040320615897144307382404804229736328125
      dataset: 0.80082819046101150206595775671303272247314453125
  Site_metadata:
    properties:
      contact:
        type: "string"
    example:
      contact: "contact"
externalDocs:
  description: "GitHub"
  url: "https://github.com/52north/ecmwf-dataset-crawl"