swagger.yaml

swagger: '2.0'
info:
  title: Linkalytics API
  description: Backend analytics to link together disparate data
  version: 1.0.1
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
  contact:
    name: Sang Han
    email: sang@qadium.com
    url: 'https://github.com/qadium-memex/linkalytics'
host: '104.197.144.112:8080'
basePath: /v1
schemes:
  - http
  - https
produces:
  - application/json
consumes:
  - application/json
securityDefinitions:
  Authentication:
    type: basic
    description: 'Will send `Authenticated` if authentication is succesful, otherwise it will send `Unauthorized`'
paths:
  /search:
    post:
      security:
        - Authentication: []
      summary: Search API
      description: |
        Search through the entity lists.
      parameters:
        - name: query
          in: body
          description: Search Query
          required: true
          schema:
            $ref: '#/definitions/SearchQuery'
      tags:
        - Search
      responses:
        '200':
          description: Response from elastic search
          schema:
            type: object
            $ref: '#/definitions/SearchResults'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /ngrams:
    post:
      security:
        - Authentication: []
      summary: n-gram distribution over documents
      description: |
        Create a Term Document Matrix containing n-grams
      parameters:
        - name: query
          in: body
          description: Search Query
          required: true
          schema:
            $ref: '#/definitions/NgramQuery'
      tags:
        - Search
        - N-Grams
      responses:
        '200':
          description: Response from elastic search
          schema:
            type: object
            $ref: '#/definitions/NgramResponse'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /lsh:
    post:
      security:
        - Authentication: []
      summary: Locality Sensitive Hashing
      description: |
        Perform nearest neighbor search over documents
      parameters:
        - name: query
          in: body
          description: Search Query
          required: true
          schema:
            $ref: '#/definitions/LSHQuery'
      tags:
        - Search
        - Locality Sensitive Hashing
      responses:
        '200':
          description: Response from elastic search
          schema:
            type: object
            $ref: '#/definitions/LSHResponse'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /coincidence:
    post:
      security:
        - Authentication: []
      summary: Check coincidences of phone number and post text
      description: |
        Provides justifications for inductive reasoning
      parameters:
        - name: query
          in: body
          description: Search Query
          required: true
          schema:
            $ref: '#/definitions/CoincidenceQuery'
      tags:
        - Search
        - Linking
      responses:
        '200':
          description: Response linking phone numbers to post text
          schema:
            type: object
            $ref: '#/definitions/CoincidenceResponse'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /imgmeta:
    post:
      security:
        - Authentication: []
      summary: 'Search through camera by id'
      description: |
        'Search through camera by id'
      parameters:
        - name: query
          in: body
          description: Search Query
          required: true
          schema:
            $ref: '#/definitions/ImageQuery'
      tags:
        - Search
        - Images
      responses:
        '200':
          description: Response linking similarities between images
          schema:
            type: object
            $ref: '#/definitions/ImageResponse'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  '/enhance/{api}':
    post:
      summary: Enhance API Endpoint
      security:
        - Authentication: []
      tags:
        - Enhance
      parameters:
        - name: api
          in: path
          required: true
          description: |
            An API endpoint defined in `[twitter, youtube, phone, instagram]`
          type: string
        - name: text
          in: body
          required: true
          description: |
            Text to send to the enhance API endpoint
          schema:
            $ref: '#/definitions/Enhance'
      responses:
        '200':
          description: Expected response to a valid request
          schema:
            $ref: '#/definitions/SearchResults'
        default:
          description: unexpected error
          schema:
            $ref: '#/definitions/Error'
definitions:
  SearchQuery:
    type: object
    properties:
      search:
        type: string
        description: Query string parameter
      size:
        type: integer
        description: Size of elasticsearch query
    title: SearchQuery
  SearchResults:
    type: object
    properties:
      results:
        type: array
        description: Result array
        items:
          $ref: '#/definitions/SearchItems'
    title: SearchResults
  SearchItems:
    type: object
    properties:
      _id:
        type: string
        description: Unique identifier representing a group of entities
      _index:
        type: string
      _source:
        $ref: '#/definitions/SearchSource'
      _type:
        type: string
    title: Search Items
  SearchSource:
    type: object
    properties:
      docs:
        type: array
        items:
          $ref: '#/definitions/SearchDocs'
    title: Search Source
  SearchDocs:
    type: object
    properties:
      _id:
        type: string
        description: Unique identifier representing an entity
      _index:
        type: string
      _source:
        type: object
    title: SearchDocs
  NgramQuery:
    type: object
    properties:
      text:
        type: string
        description: Elasticsearch query string
      size:
        type: integer
        description: Maximum size of the elasticsearch query
      ngrams:
        type: integer
        description: Amount of n-grams to separate query
    title: Ngram Query
  NgramResponse:
    type: object
    properties:
      results:
        type: object
        description: Response from querying ngrams
        $ref: '#/definitions/NgramResults'
    title: Ngram Response
  NgramResults:
    type: object
    properties:
      ngram:
        type: array
        description: A list of all ngrams containing this result
        $ref: '#/definitions/NgramDocs'
    title: Ngram Results
  NgramDocs:
    type: string
    description: "Document ID's cooresponding to linked ngrams"
  LSHQuery:
    type: object
    properties:
      text:
        type: string
        description: Elasticsearch query string
      size:
        type: integer
        description: Maximum size of the elasticsearch query
    title: LSH Query
  LSHResponse:
    type: object
    properties:
      doc_id:
        type: array
        description: "Document ID's cooresponding to nearest neighbors"
        $ref: '#/definitions/LSHResults'
  LSHResults:
    type: array
    items:
      $ref: '#/definitions/LSHItems'
  LSHItems:
    type: object
    properties:
      doc_id:
        type: string
        description: Body string from the document
  CoincidenceQuery:
    type: object
    properties:
      text:
        type: string
        description: Elasticsearch query string
      size:
        type: integer
        description: Maximum size of the elasticsearch query
    title: Coincidence Query
  CoincidenceResponse:
    type: object
    properties:
      final_date:
        type: string
        format: date
      initial_date:
        type: string
        format: date
      phrase:
        type: string
      results:
        type: object
        $ref: '#/definitions/CoincidenceResults'
  CoincidenceResults:
    type: object
    properties:
      doc_id:
        type: object
        description: Document ID
        $ref: '#/definitions/CoincidenceDoc'
  CoincidenceDoc:
    type: object
    properties:
      date:
        type: object
        description: Dates of entry
        $ref: '#/definitions/CoincidenceDates'
      results:
        type: object
        description: Coincidence matches
        $ref: '#/definitions/CoincidenceItems'
  CoincidenceDates:
    type: object
    properties:
      initial:
        type: string
        description: Initial Date
        format: date
      final:
        type: string
        description: Final Date
        format: date
  CoincidenceItems:
    type: object
    properties:
      phone:
        type: integer
        description: Phone numbers from this query
      both:
        type: integer
        description: Entries matching both same text and same phone number
  ImageQuery:
    type: object
    properties:
      id:
        type: string
        description: Model ID number
  ImageResponse:
    type: object
  Enhance:
    type: object
    properties:
      text:
        type: string
        description: Text to send to the enhance api endpoint
    title: Enhance
  Error:
    type: object
    properties:
      code:
        type: integer
        format: int32
      message:
        type: string
      fields:
        type: string
    title: Error