api.yaml

swagger: '2.0'
info:
  title: Grakn
  description: 'API for clients to interact with Grakn'
  version: "0.1"
schemes: [http]
host: localhost:4567
paths:
  /:
    get:
      summary: Root
      tags: [Root]
      produces: [application/json]
      responses:
        200:
          description: ''
          schema:
            $ref: '#/definitions/Root'
  /kb:
    get:
      summary: Get Knowledge Graphs
      tags: [Keyspaces]
      produces: [application/json]
      responses:
        200:
          description: ''
          schema:
            $ref: '#/definitions/KnowledgeBases'
  /kb/{keyspace}:
    parameters:
      - $ref: '#/parameters/keyspace'
    get:
      summary: Get Knowledge Graph
      tags: [Keyspaces]
      produces: [application/json]
      responses:
        200:
          description: ''
          schema:
            $ref: '#/definitions/KnowledgeBase'
        404:
          description: ''
    put:
      summary: Put Knowledge Graph
      description: >-
        If the keyspace exists, nothing happens. The configuration is returned. This response is the same as the
        response from `/kb/configuration`.
      tags: [Keyspaces]
      produces: [application/json]
      responses:
        200:
          description: ''
          schema:
            $ref: '#/definitions/Configuration'
    delete:
      summary: Delete Knowledge Graph
      description: >-
        If the keyspace doesn't exist, nothing happens.
      tags: [Keyspaces]
      responses:
        204:
          description: ''
  /kb/{keyspace}/graql:
    post:
      summary: Execute Graql Query
      tags: [Keyspaces]
      parameters:
      - $ref: '#/parameters/keyspace'
      - name: infer
        in: query
        description: Enable inference
        type: boolean
      - name: defineAllVars
        in: query
        description: Define all anonymous variables in the query
        type: boolean
      - name: multi
        in: query
        description: Support multiple queries
        type: boolean
      - name: explain
        in: query
        description: Provide an explanation of how results were inferred
        type: boolean
      - name: txType
        in: query
        description: Mode to operate Graql in (one of read, write or batch). Defaults to write.
        type: string
      - name: body
        in: body
        schema:
          $ref: '#/definitions/GraqlQuery'
        required: true
      produces: [text/plain, application/json]
      responses:
        200:
          description: 'Returns a Graql query response. This can be different depending on the type of query.'
          schema:
            $ref: '#/definitions/GraqlResponse'
        400:
          description: ''
  /kb/{keyspace}/concept/{id}:
    get:
      summary: Get Concept
      tags: [Concepts]
      parameters:
      - $ref: '#/parameters/keyspace'
      - name: id
        in: path
        required: true
        type: string
        x-example: V123
#       For OpenAPI 3.0
#       schema:
#         $ref: '#/definitions/ConceptID'
      produces: [application/json]
      responses:
        200:
          description: ''
          schema:
            $ref: '#/definitions/AnyConcept'
        404:
          description: ''
  /kb/{keyspace}/concept/{id}/relationships:
    get:
      summary: Get Relationships
      tags: [Concepts]
      parameters:
      - $ref: '#/parameters/keyspace'
      - name: id
        in: path
        required: true
        type: string
        x-example: V123
#       For OpenAPI 3.0
#       schema:
#         $ref: '#/definitions/ConceptID'
      produces: [application/json]
      responses:
        200:
          description: ''
          schema:
            $ref: '#/definitions/Relationships'
  /kb/{keyspace}/concept/{id}/attributes:
    get:
      summary: Get Attributes
      tags: [Concepts]
      parameters:
      - $ref: '#/parameters/keyspace'
      - name: id
        in: path
        required: true
        type: string
        x-example: V123
#       For OpenAPI 3.0
#       schema:
#         $ref: '#/definitions/ConceptID'
      produces: [application/json]
      responses:
        200:
          description: ''
          schema:
            $ref: '#/definitions/Attributes'
  /kb/{keyspace}/concept/{id}/keys:
    get:
      summary: Get Keys
      tags: [Concepts]
      parameters:
      - $ref: '#/parameters/keyspace'
      - name: id
        in: path
        required: true
        type: string
        x-example: V123
#       For OpenAPI 3.0
#       schema:
#         $ref: '#/definitions/ConceptID'
      produces: [application/json]
      responses:
        200:
          description: ''
          schema:
            $ref: '#/definitions/Keys'
  /kb/{keyspace}/type:
    get:
      summary: Get Types
      tags: [Concepts]
      parameters:
      - $ref: '#/parameters/keyspace'
      produces: [application/json]
      responses:
        200:
          description: ''
          schema:
            $ref: '#/definitions/Types'
  /kb/{keyspace}/type/{label}:
    get:
      summary: Get Type
      tags: [Concepts]
      parameters:
      - $ref: '#/parameters/keyspace'
      - $ref: '#/parameters/label'
      produces: [application/json]
      responses:
        200:
          description: ''
          schema:
            $ref: '#/definitions/Type'
        404:
          description: ''
  /kb/{keyspace}/type/{label}/instances:
    get:
      summary: Get Instances
      tags: [Concepts]
      parameters:
      - $ref: '#/parameters/keyspace'
      - $ref: '#/parameters/label'
      - $ref: '#/parameters/limit'
      - $ref: '#/parameters/offset'
      produces: [application/json]
      responses:
        200:
          description: ''
          schema:
            $ref: '#/definitions/Instances'
        404:
          description: ''
  /kb/{keyspace}/type/{label}/subs:
    get:
      summary: Get Sub-Types
      tags: [Concepts]
      parameters:
      - $ref: '#/parameters/keyspace'
      - $ref: '#/parameters/label'
      produces: [application/json]
      responses:
        200:
          description: ''
          schema:
            $ref: '#/definitions/SubTypes'
        404:
          description: ''
  /kb/{keyspace}/type/{label}/plays:
    get:
      summary: Get Roles Played
      tags: [Concepts]
      parameters:
      - $ref: '#/parameters/keyspace'
      - $ref: '#/parameters/label'
      produces: [application/json]
      responses:
        200:
          description: ''
          schema:
            $ref: '#/definitions/Plays'
        404:
          description: ''
  /kb/{keyspace}/type/{label}/attributes:
    get:
      summary: Get Attributes
      tags: [Concepts]
      parameters:
      - $ref: '#/parameters/keyspace'
      - $ref: '#/parameters/label'
      produces: [application/json]
      responses:
        200:
          description: ''
          schema:
            $ref: '#/definitions/AttributeTypes'
        404:
          description: ''
  /kb/{keyspace}/type/{label}/keys:
    get:
      summary: Get Keys
      tags: [Concepts]
      parameters:
      - $ref: '#/parameters/keyspace'
      - $ref: '#/parameters/label'
      produces: [application/json]
      responses:
        200:
          description: ''
          schema:
            $ref: '#/definitions/KeyTypes'
        404:
          description: ''
  /kb/{keyspace}/role:
    get:
      summary: Get Roles
      tags: [Concepts]
      parameters:
      - $ref: '#/parameters/keyspace'
      produces: [application/json]
      responses:
        200:
          description: ''
          schema:
            $ref: '#/definitions/Roles'
  /kb/{keyspace}/role/{label}:
    get:
      summary: Get Role
      tags: [Concepts]
      parameters:
      - $ref: '#/parameters/keyspace'
      - $ref: '#/parameters/label'
      produces: [application/json]
      responses:
        200:
          description: ''
          schema:
            $ref: '#/definitions/Role'
        404:
          description: ''
  /kb/{keyspace}/role/{label}/subs:
    get:
      summary: Get Sub-Roles
      tags: [Concepts]
      parameters:
      - $ref: '#/parameters/keyspace'
      - $ref: '#/parameters/label'
      produces: [application/json]
      responses:
        200:
          description: ''
          schema:
            $ref: '#/definitions/SubRoles'
        404:
          description: ''
  /kb/{keyspace}/rule:
    get:
      summary: Get Rules
      tags: [Concepts]
      parameters:
      - $ref: '#/parameters/keyspace'
      produces: [application/json]
      responses:
        200:
          description: ''
          schema:
            $ref: '#/definitions/Rules'
  /kb/{keyspace}/rule/{label}:
    get:
      summary: Get Rule
      tags: [Concepts]
      parameters:
      - $ref: '#/parameters/keyspace'
      - $ref: '#/parameters/label'
      produces: [application/json]
      responses:
        200:
          description: ''
          schema:
            $ref: '#/definitions/Rule'
        404:
          description: ''
  /kb/{keyspace}/rule/{label}/subs:
    get:
      summary: Get Sub-Rules
      tags: [Concepts]
      parameters:
      - $ref: '#/parameters/keyspace'
      - $ref: '#/parameters/label'
      produces: [application/json]
      responses:
        200:
          description: ''
          schema:
            $ref: '#/definitions/SubRules'
        404:
          description: ''
  /status:
    get:
      summary: Get Status
      tags: [Internal]
      produces: [application/json]
      responses:
        200:
          description: ''
          schema:
            $ref: '#/definitions/StatusResponse'
  /metrics:
    get:
      summary: Get Metrics
      tags: [Internal]
      produces: [text/plain]
      responses:
        200:
          description: ''
          schema:
            type: object
  /kb/{keyspace}/commit_log:
    post:
      summary: Post Commit Log
      tags: [Internal]
      parameters:
      - $ref: '#/parameters/keyspace'
      - name: body
        in: body
        schema:
          $ref: '#/definitions/CommitLogRequest'
        required: true
      responses:
        200:
          description: ''
parameters:
  keyspace:
    name: keyspace
    in: path
    required: true
    type: string
    x-example: genealogy
#   For OpenAPI 3.0
#   schema:
#     $ref: '#/definitions/Keyspace'
  label:
    name: label
    in: path
    required: true
    type: string
    x-example: person
#   For OpenAPI 3.0
#   schema:
#     $ref: '#/definitions/Label'
  limit:
    name: limit
    in: query
    type: number
  offset:
    name: offset
    in: query
    type: number
definitions:
  Root:
    type: object
    required: ['@id', keyspaces]
    properties:
      '@id':
        type: string
        format: uri
        example: /
      keyspaces:
        $ref: '#/definitions/KnowledgeBasesLink'
  KnowledgeBasesLink:
    type: string
    format: uri
    example: /kb
  KnowledgeBases:
    type: object
    required: ['@id', keyspaces, keyspace]
    properties:
      '@id':
        $ref: '#/definitions/KnowledgeBasesLink'
      keyspaces:
        type: array
        items:
          $ref: '#/definitions/KnowledgeBase'
      keyspace:
        type: string
        format: uri
        example: /kb/{keyspace}
  Keyspace:
    type: string
    example: genealogy
  KnowledgeBase:
    required: ['@id', name, types, roles, rules, graql]
    type: object
    properties:
      '@id':
        type: string
        example: /kb/genealogy
      name:
        $ref: '#/definitions/Keyspace'
      types:
        $ref: '#/definitions/TypesLink'
      roles:
        $ref: '#/definitions/RolesLink'
      rules:
        $ref: '#/definitions/RulesLink'
      graql:
        type: string
        format: uri
        example: /kb/genealogy/graql
  Label:
    type: string
    example: person
  ConceptLink:
    type: string
    format: uri
    example: /kb/genealogy/concept/V123
  Concept:
    required: [id, 'base-type']
    type: object
    properties:
      id:
        $ref: '#/definitions/ConceptID'
      'base-type':
        type: string
  AnyConcept:
    $ref: '#/definitions/Thing'
#   For OpenAPI 3.0
#   oneOf:
#     - $ref: '#/definitions/Thing'
#     - $ref: '#/definitions/Type'
#     - $ref: '#/definitions/Role'
#     - $ref: '#/definitions/Rule'
#   example:
#     '@id': /kb/genealogy/concept/V123
#     type:
#       '@id': /kb/genealogy/type/person
#       label: person
#     relationships:
#     - role: /kb/genealogy/role/husband
#       relationship: /kb/genealogy/concept/V456
#     attributes:
#     - '@id': /kb/genealogy/concept/V321
#       type:
#         '@id': /kb/genealogy/type/name
#         label: name
#        value: 'Bob'
#     keys:
#     - '@id': /kb/genealogy/concept/V654
#       type:
#         '@id': /kb/genealogy/type/person-id
#         label: person-id
#       value: 808
  Thing:
    allOf:
      - $ref: '#/definitions/Concept'
      - type: object
      - required: ['@id', type, relationships, attributes, keys, inferred]
        properties:
          '@id':
            $ref: '#/definitions/ConceptLink'
          type:
            $ref: '#/definitions/TypeSummary'
          relationships:
            $ref: '#/definitions/RelationshipsLink'
          attributes:
            $ref: '#/definitions/AttributesLink'
          keys:
            $ref: '#/definitions/KeysLink'
          roleplayers:
            type: array
            items:
              $ref: '#/definitions/RolePlayers'
          value:
            $ref: '#/definitions/Value'
          inferred:
            type: boolean
          'base-type':
            enum: ['ENTITY', 'RELATIONSHIP', 'ATTRIBUTE']
  RolePlayers:
    required: [role, thing]
    type: object
    properties:
      role:
        $ref: '#/definitions/RoleLink'
      thing:
        $ref: '#/definitions/ConceptLink'
  AttributeSummary:
    type: object
    required: ['@id', type, value]
    properties:
      '@id':
        $ref: '#/definitions/ConceptLink'
      type:
        $ref: '#/definitions/TypeSummary'
      value:
        $ref: '#/definitions/Value'
  Value:
    {}
#   For OpenAPI 3.0
#   anyOf:
#     - type: string
#     - type: number
#     - type: boolean
  RelationshipsLink:
    type: string
    format: uri
    example: /kb/genealogy/concept/V123/relationships
  Relationships:
    required: ['@id', relationships]
    type: object
    properties:
      '@id':
        allOf: [$ref: '#/definitions/RelationshipsLink']
        example: /kb/genealogy/concept/V123/relationships?limit=100&offset=100
      relationships:
        type: array
        items:
          $ref: '#/definitions/RolePlayers'
      next:
        allOf: [$ref: '#/definitions/RelationshipsLink']
        example: /kb/genealogy/concept/V123/relationships?limit=100&offset=200
      previous:
        allOf: [$ref: '#/definitions/RelationshipsLink']
        example: /kb/genealogy/concept/V123/relationships?limit=100&offset=0
  KeysLink:
    type: string
    format: uri
    example: /kb/genealogy/concept/V123/keys
  Keys:
    required: ['@id', keys]
    type: object
    properties:
      '@id':
        allOf: [$ref: '#/definitions/KeysLink']
        example: /kb/genealogy/concept/V123/keys?limit=100&offset=100
      keys:
        type: array
        items:
          $ref: '#/definitions/AttributeSummary'
      next:
        allOf: [$ref: '#/definitions/KeysLink']
        example: /kb/genealogy/concept/V123/keys?limit=100&offset=200
      previous:
        allOf: [$ref: '#/definitions/KeysLink']
        example: /kb/genealogy/concept/V123/keys?limit=100&offset=0
  AttributesLink:
    type: string
    format: uri
    example: /kb/genealogy/concept/V123/attributes
  Attributes:
    required: ['@id', attributes]
    type: object
    properties:
      '@id':
        allOf: [$ref: '#/definitions/AttributesLink']
        example: /kb/genealogy/concept/V123/attributes?limit=100&offset=100
      attributes:
        type: array
        items:
          $ref: '#/definitions/AttributeSummary'
      next:
        allOf: [$ref: '#/definitions/AttributesLink']
        example: /kb/genealogy/concept/V123/attributes?limit=100&offset=200
      previous:
        allOf: [$ref: '#/definitions/AttributesLink']
        example: /kb/genealogy/concept/V123/attributes?limit=100&offset=0
  TypesLink:
    type: string
    format: uri
    example: /kb/genealogy/type
  Types:
    type: object
    required: ['@id', types]
    properties:
      '@id':
        $ref: '#/definitions/TypesLink'
      types:
        type: array
        items:
          $ref: '#/definitions/Type'
  TypeLink:
    type: string
    format: uri
    example: /kb/genealogy/type/person
  TypeSummary:
    required: ['@id', label]
    type: object
    properties:
      '@id':
        $ref: '#/definitions/TypeLink'
      label:
        $ref: '#/definitions/Label'
  Type:
    allOf:
      - $ref: '#/definitions/TypeSummary'
      - $ref: '#/definitions/SchemaConcept'
      - required: [abstract, plays, attributes, keys, subs]
        type: object
        properties:
          abstract:
            type: boolean
          plays:
            $ref: '#/definitions/PlaysLink'
          attributes:
            $ref: '#/definitions/AttributeTypesLink'
          keys:
            $ref: '#/definitions/KeyTypesLink'
          subs:
            $ref: '#/definitions/SubTypesLink'
          relates:
            type: array
            items:
              $ref: '#/definitions/RoleLink'
          super:
            allOf: [$ref: '#/definitions/TypeSummary']
            example:
              '@id': /kb/genealogy/type/entity
              label: entity
          instances:
            $ref: '#/definitions/InstancesLink'
          'base-type':
            enum: ['TYPE', 'ENTITY_TYPE', 'RELATIONSHIP_TYPE', 'ATTRIBUTE_TYPE']
  InstancesLink:
    type: string
    format: uri
    example: /kb/genealogy/type/person/instances
  Instances:
    required: ['@id', instances]
    type: object
    properties:
      '@id':
        allOf: [$ref: '#/definitions/InstancesLink']
        example: /kb/genealogy/type/person/instances?limit=100&offset=100
      instances:
        type: array
        items:
          $ref: '#/definitions/Concept'
      next:
        allOf: [$ref: '#/definitions/InstancesLink']
        example: /kb/genealogy/type/person/instances?limit=100&offset=200
      previous:
        allOf: [$ref: '#/definitions/InstancesLink']
        example: /kb/genealogy/type/person/instances?limit=100&offset=0
  SubTypesLink:
    type: string
    format: uri
    example: /kb/genealogy/type/person/subs
  SubTypes:
    type: object
    required: ['@id', subs]
    properties:
      '@id':
        $ref: '#/definitions/SubTypesLink'
      subs:
        type: array
        items:
          $ref: '#/definitions/Type'
  PlaysLink:
    type: string
    format: uri
    example: /kb/genealogy/type/person/plays
  Plays:
    type: object
    required: ['@id', plays]
    properties:
      '@id':
        $ref: '#/definitions/PlaysLink'
      plays:
        type: array
        items:
          $ref: '#/definitions/Role'
  AttributeTypesLink:
    type: string
    format: uri
    example: /kb/genealogy/type/person/attributes
  AttributeTypes:
    type: object
    required: ['@id', attributes]
    properties:
      '@id':
        $ref: '#/definitions/AttributeTypesLink'
      attributes:
        type: array
        items:
          $ref: '#/definitions/AttributeType'
  KeyTypesLink:
    type: string
    format: uri
    example: /kb/genealogy/type/person/keys
  KeyTypes:
    type: object
    required: ['@id', keys]
    properties:
      '@id':
        $ref: '#/definitions/KeyTypesLink'
      keys:
        type: array
        items:
          $ref: '#/definitions/AttributeType'
  AttributeType:
    allOf:
      - $ref: '#/definitions/Type'
      - properties:
          '@id':
            example: /kb/genealogy/type/name
          label:
            example: name
          'base-type':
            enum: ['ATTRIBUTE_TYPE']
  RoleLink:
    type: string
    format: uri
    example: /kb/genealogy/role/husband
  RolesLink:
    type: string
    format: uri
    example: /kb/genealogy/role
  RoleSummary:
    required: ['@id', label]
    type: object
    properties:
      '@id':
        $ref: '#/definitions/RoleLink'
      label:
        $ref: '#/definitions/Label'
  Roles:
    type: object
    required: ['@id', roles]
    properties:
      '@id':
        $ref: '#/definitions/RolesLink'
      roles:
        type: array
        items:
          $ref: '#/definitions/Role'
  Role:
    allOf:
      - $ref: '#/definitions/TypeSummary'
      - $ref: '#/definitions/SchemaConcept'
      - type: object
        required: [relationships, roleplayers, subs]
        properties:
          '@id':
            example: /kb/genealogy/role/husband
          label:
            example: husband
          relationships:
            type: array
            items:
              $ref: '#/definitions/TypeLink'
          roleplayers:
            type: array
            items:
              allOf: [$ref: '#/definitions/TypeLink']
              example: /kb/genealogy/type/marriage
          subs:
            $ref: '#/definitions/SubRolesLink'
          super:
            allOf: [$ref: '#/definitions/RoleSummary']
            example:
              '@id': /kb/genealogy/role/spouse
              label: spouse
          'base-type':
            enum: ['ROLE']
  SubRolesLink:
    type: string
    format: uri
    example: /kb/genealogy/role/husband/subs
  SubRoles:
    type: object
    required: ['@id', subs]
    properties:
      '@id':
        $ref: '#/definitions/SubRolesLink'
      subs:
        type: array
        items:
          $ref: '#/definitions/Role'
  RuleLink:
    type: string
    format: uri
    example: /kb/genealogy/rule/grandparent-rule
  RulesLink:
    type: string
    format: uri
    example: /kb/genealogy/rule
  RuleSummary:
    required: ['@id', label]
    type: object
    properties:
      '@id':
        $ref: '#/definitions/RuleLink'
      label:
        $ref: '#/definitions/Label'
  Rules:
    type: object
    required: ['@id', rules]
    properties:
      '@id':
        $ref: '#/definitions/RulesLink'
      rules:
        type: array
        items:
          $ref: '#/definitions/Rule'
  Rule:
    allOf:
      - $ref: '#/definitions/RuleSummary'
      - $ref: '#/definitions/SchemaConcept'
      - type: object
        required: [id, label, when, then]
        properties:
          subs:
            $ref: '#/definitions/SubRulesLink'
          super:
            allOf: [$ref: '#/definitions/RuleSummary']
            example:
              '@id': /kb/genealogy/rule/rule
              label: rule
          label:
            allOf: [$ref: '#/definitions/Label']
            example: grandparent-rule
          when:
            type: string
            example: '(parent: $x, child: $y); (parent: $y, child: $z);'
          then:
            type: string
            example: '(grandparent: $x, grandchild: $y) isa grandparentship;'
          'base-type':
            enum: ['RULE']
  SubRulesLink:
    type: string
    format: uri
    example: /kb/genealogy/rule/grandparent-rule/subs
  SubRules:
    type: object
    required: ['@id', subs]
    properties:
      '@id':
        $ref: '#/definitions/SubRulesLink'
      subs:
        type: array
        items:
          $ref: '#/definitions/Rule'
  SchemaConcept:
    allOf:
      - $ref: '#/definitions/Concept'
      - type: object
        required: [implicit]
        properties:
          implicit:
            type: boolean
  Answer:
    type: object
    additionalProperties:
      $ref: '#/definitions/Concept'
  Configuration:
    type: object
#   For OpenAPI 3.0
#   additionalProperties:
#     oneOf:
#       - type: string
#       - type: number
#       - type: boolean
    example:
      knowledge-base.mode: production
      knowledge-base.analytics: distributed
      knowledge-base.default-keyspace: grakn
      knowledge-base.sharding-threshold: 10000
      knowledge-base.schema-cache-timeout-ms: 600000
      server.host: 0.0.0.0
      server.port: 4567
      server.static-file-dir: ../services/assets/
      loader.repeat-commits: 5
      tasks.postprocessing.delay: 60000
      loader.threads: 4
      webserver.threads: 64
      log.dirs: ../logs/
      log.level: INFO
      storage.backend: grakn-production
      storage.hostname: 127.0.0.1
      cache.db-cache: true
      cache.db-cache-clean-wait: 20
      cache.db-cache-time: 180000
      cache.db-cache-size: 0.25
      queue.host: localhost:6379
      queue.consumers: 32
      redis.pool-size: 32
  StatusResponse:
    type: object
    properties:
      status:
        type: string
        enum:
          - READY
          - INITIALIZING
  CommitLogRequest:
    type: object
    required: [instance-count, new-attributes]
    properties:
      instance-count:
        additionalProperties:
          type: number
        example:
          V123: 100
          V456: 3
      new-attributes:
        additionalProperties:
          type: array
          items:
            $ref: '#/definitions/ConceptID'
        example:
          AttributeIndex-name-Bob: [V789, V987]
  ConceptID:
    type: string
    example: V123
  GraqlQuery:
    type: string
    example: 'match $x isa person; get;'
  GraqlResponse:
    type: array
    items:
      $ref: '#/definitions/Answer'