swagger: "2.0"
schemes:
  - https
host: api.digitallinguistics.io
basePath: /v0
info:
  contact:
    email: dhieber@umail.ucsb.edu
    name: Daniel W. Hieber
    url: http://danielhieber.com/
  description: The Digital Linguistics (DLx) REST API
  license:
    name: MIT
  title: DLx
  version: 0.3.1
  x-apisguru-categories:
    - text
  x-logo:
    backgroundColor: "#FFFFFF"
    url: https://avatars3.githubusercontent.com/u/5896943?s=200&v=4
  x-origin:
    - format: swagger
      url: https://raw.githubusercontent.com/digitallinguistics/api/master/public/swagger/swagger.json
      version: "2.0"
  x-providerName: digitallinguistics.io
externalDocs:
  description: How to use the API
  url: http://developer.digitallinguistics.io/api/
consumes:
  - application/json
produces:
  - application/json
securityDefinitions:
  Authorization:
    description: An access token (JSON Web Token) included in the `Authorization` header in the format `Bearer {token}`. Tokens may be retrieved programmatically from https://digitallinguistics.auth0.com. See the authorization documentation at http://developer.digitallinguistics.io/api/.
    in: header
    name: Authorization
    type: apiKey
security:
  - Authorization: []
parameters:
  body:
    description: A database resource to upsert
    in: body
    name: body
    required: true
    schema:
      type: object
  continuation:
    description: The `dlx-continuation` header is used to send a continuation token with the request, when retrieving the next page of results.
    in: header
    name: continuation
    required: false
    type: string
  deleted:
    default: false
    description: Setting the `deleted` option to `true` will return results that have been marked for deletion, but not yet deleted from the database. Otherwise requests for a resource marked for deletion will return a 410 error.
    in: query
    name: deleted
    required: false
    type: boolean
  ifMatch:
    description: The `If-Match` header is used with PUT and DELETE requests to check whether you have the most up-to-date version of the resource before updating or deleting it. The value of the `If-Match` header is the ETag (`_etag`) property of the resource. It is recommended that your application use this header whenever possible to avoid data conflicts.
    in: header
    name: ifMatch
    required: false
    type: string
  ifModifiedSince:
    description: The `If-Modified-Since` header is used to retrieve only results modified since a given time. The value of this header must be a valid date string.
    in: header
    name: ifModifiedSince
    required: false
    type: string
  ifNoneMatch:
    description: If `If-None-Match` header is used with GET requests to check whether you already have the most up-to-date version of the resource, and therefore do not need the resource sent again. The value of the `If-None-Match` header is the ETag (`_etag`) property of the resource. It is recommended that your application use this header whenever possible to reduce bandwidth.
    in: header
    name: ifNoneMatch
    required: false
    type: string
  languageID:
    description: The ID of the Language to perform the operation on
    in: path
    name: languageID
    required: true
    type: string
  languageIDProp:
    description: The ID of the Language to perform the operation on
    in: body
    name: languageID
    required: false
    schema:
      properties:
        languageID:
          type: string
      required:
        - languageID
  languageIDQuery:
    allowEmptyValue: true
    description: The ID of the Language to perform the operation on
    in: query
    name: languageID
    required: false
    type: string
  lexemeID:
    description: The ID of the Lexeme to perform the operation on
    in: path
    name: lexemeID
    required: true
    type: string
  maxItemCount:
    description: The `dlx-max-item-count` header is used to limit the number of results to a certain amount at a time (by default all results will be returned). If there are more results to be returned, a continuation token will also be sent in the `dlx-continuation` header.
    in: header
    name: maxItemCount
    required: false
    type: string
  public:
    default: "false"
    description: Set this parameter to `true` to include all publicly-accessible resources, not just those that the user is listed as an Owner, Contributor, or Viewer for.
    in: query
    name: public
    required: false
    type: string
responses:
  BadRequest:
    description: "400: There was a problem with the request."
  Conflict:
    description: "409: There was a data conflict in the database."
  Created:
    description: "201: The resource was created successfully."
    headers:
      Last-Modified:
        description: The time that the item was last modified
        type: string
  DeleteSuccessful:
    description: "204: Delete operation successful."
  Forbidden:
    description: "403: Unauthorized."
  LargePayload:
    description: "413: Request payload is too large."
  MethodNotAllowed:
    description: "405: Method not allowed."
  NotAcceptable:
    description: "406: Cannot return data in requested format."
  NotFound:
    description: "404: Database resource not found."
  NotImplemented:
    description: "501: This feature is not yet implemented."
  NotModified:
    description: "304: Not modified."
  PreconditionFailed:
    description: "412: A precondition for the operation was not met."
  RetryOperation:
    description: "449: Retry the operation"
  ServerError:
    description: "500: An error occurred on the server."
  Success:
    description: "200: Operation successful."
    headers:
      Last-Modified:
        description: The time that the item was last modified
        type: string
      dlx-continuation:
        description: A continuation token for retrieving more results
        type: string
      dlx-item-count:
        description: The number of items returned in the response
        type: string
  Timeout:
    description: "408: The request timed out."
  TokenExpired:
    description: "419: Access token expired."
  TooManyRequests:
    description: "429: Too many requests."
  Unauthorized:
    description: "401: Authorization missing or invalid."
    headers:
      WWW-Authenticate:
        description: An access token is required.
        type: string
  Unprocessable:
    description: "422: The data is not properly formatted."
  UpdateSuccessful:
    description: "200: Update successful."
    headers:
      Last-Modified:
        description: The time that the item was last modified
        type: string
  UpsertSuccessful:
    description: "201: Upsert successful."
    headers:
      Last-Modified:
        description: The time that the item was last modified
        type: string
tags:
  - description: Operations on Languages
    name: Language
  - description: Operations on Lexemes
    name: Lexeme
paths:
  /languages:
    get:
      description: Retrieves all the Languages that the authenticated user or client has permission to access.
      operationId: getLanguages
      parameters:
        - description: The `dlx-continuation` header is used to send a continuation token with the request, when retrieving the next page of results.
          in: header
          name: continuation
          required: false
          type: string
        - default: false
          description: Setting the `deleted` option to `true` will return results that have been marked for deletion, but not yet deleted from the database. Otherwise requests for a resource marked for deletion will return a 410 error.
          in: query
          name: deleted
          required: false
          type: boolean
        - description: The `If-Modified-Since` header is used to retrieve only results modified since a given time. The value of this header must be a valid date string.
          in: header
          name: ifModifiedSince
          required: false
          type: string
        - description: The `dlx-max-item-count` header is used to limit the number of results to a certain amount at a time (by default all results will be returned). If there are more results to be returned, a continuation token will also be sent in the `dlx-continuation` header.
          in: header
          name: maxItemCount
          required: false
          type: string
        - default: "false"
          description: Set this parameter to `true` to include all publicly-accessible resources, not just those that the user is listed as an Owner, Contributor, or Viewer for.
          in: query
          name: public
          required: false
          type: string
      responses:
        "200":
          description: "200: Operation successful."
          headers:
            Last-Modified:
              description: The time that the item was last modified
              type: string
            dlx-continuation:
              description: A continuation token for retrieving more results
              type: string
            dlx-item-count:
              description: The number of items returned in the response
              type: string
      summary: Get all Languages
      tags:
        - Language
    post:
      operationId: addLanguage
      parameters:
        - description: A database resource to upsert
          in: body
          name: body
          required: true
          schema:
            type: object
      responses:
        "201":
          description: "201: The resource was created successfully."
          headers:
            Last-Modified:
              description: The time that the item was last modified
              type: string
      summary: Add a new Language
      tags:
        - Language
    put:
      description: Creates a Language if it does not yet exist (i.e. if the resource does not have an `id` property yet), or replaces the existing Language resource if it does. Note that this replaces the *entire* Language. It is not a partial update.
      operationId: upsertLanguage
      parameters:
        - description: A database resource to upsert
          in: body
          name: body
          required: true
          schema:
            type: object
        - description: The `If-Match` header is used with PUT and DELETE requests to check whether you have the most up-to-date version of the resource before updating or deleting it. The value of the `If-Match` header is the ETag (`_etag`) property of the resource. It is recommended that your application use this header whenever possible to avoid data conflicts.
          in: header
          name: ifMatch
          required: false
          type: string
      responses:
        "201":
          description: "201: Upsert successful."
          headers:
            Last-Modified:
              description: The time that the item was last modified
              type: string
      summary: Upsert (create or replace) a Language
      tags:
        - Language
  "/languages/{languageID}":
    delete:
      operationId: deleteLanguage
      parameters:
        - description: The ID of the Language to perform the operation on
          in: path
          name: languageID
          required: true
          type: string
        - description: The `If-Match` header is used with PUT and DELETE requests to check whether you have the most up-to-date version of the resource before updating or deleting it. The value of the `If-Match` header is the ETag (`_etag`) property of the resource. It is recommended that your application use this header whenever possible to avoid data conflicts.
          in: header
          name: ifMatch
          required: false
          type: string
      responses:
        "204":
          description: "204: Delete operation successful."
      summary: Delete a Language by ID
      tags:
        - Language
    get:
      operationId: getLanguage
      parameters:
        - description: The ID of the Language to perform the operation on
          in: path
          name: languageID
          required: true
          type: string
        - default: false
          description: Setting the `deleted` option to `true` will return results that have been marked for deletion, but not yet deleted from the database. Otherwise requests for a resource marked for deletion will return a 410 error.
          in: query
          name: deleted
          required: false
          type: boolean
        - description: If `If-None-Match` header is used with GET requests to check whether you already have the most up-to-date version of the resource, and therefore do not need the resource sent again. The value of the `If-None-Match` header is the ETag (`_etag`) property of the resource. It is recommended that your application use this header whenever possible to reduce bandwidth.
          in: header
          name: ifNoneMatch
          required: false
          type: string
      responses:
        "200":
          description: "200: Operation successful."
          headers:
            Last-Modified:
              description: The time that the item was last modified
              type: string
            dlx-continuation:
              description: A continuation token for retrieving more results
              type: string
            dlx-item-count:
              description: The number of items returned in the response
              type: string
        "304":
          description: "304: Not modified."
      summary: Retrieve a Language by ID
      tags:
        - Language
    patch:
      description: Performs a partial update the Language whose ID is specified in the URL. If the Language object has an `id` property, is ignored in favor of the ID in the URL.
      operationId: updateLanguage
      parameters:
        - description: The ID of the Language to perform the operation on
          in: path
          name: languageID
          required: true
          type: string
        - description: A database resource to upsert
          in: body
          name: body
          required: true
          schema:
            type: object
        - description: The `If-Match` header is used with PUT and DELETE requests to check whether you have the most up-to-date version of the resource before updating or deleting it. The value of the `If-Match` header is the ETag (`_etag`) property of the resource. It is recommended that your application use this header whenever possible to avoid data conflicts.
          in: header
          name: ifMatch
          required: false
          type: string
      responses:
        "200":
          description: "200: Update successful."
          headers:
            Last-Modified:
              description: The time that the item was last modified
              type: string
      summary: Perform a partial update on a Language
      tags:
        - Language
  "/languages/{languageID}/lexemes":
    get:
      operationId: getLexemesByLanguage
      parameters:
        - description: The ID of the Language to perform the operation on
          in: path
          name: languageID
          required: true
          type: string
        - description: The `dlx-continuation` header is used to send a continuation token with the request, when retrieving the next page of results.
          in: header
          name: continuation
          required: false
          type: string
        - default: false
          description: Setting the `deleted` option to `true` will return results that have been marked for deletion, but not yet deleted from the database. Otherwise requests for a resource marked for deletion will return a 410 error.
          in: query
          name: deleted
          required: false
          type: boolean
        - description: The `If-Modified-Since` header is used to retrieve only results modified since a given time. The value of this header must be a valid date string.
          in: header
          name: ifModifiedSince
          required: false
          type: string
        - description: The `dlx-max-item-count` header is used to limit the number of results to a certain amount at a time (by default all results will be returned). If there are more results to be returned, a continuation token will also be sent in the `dlx-continuation` header.
          in: header
          name: maxItemCount
          required: false
          type: string
        - default: "false"
          description: Set this parameter to `true` to include all publicly-accessible resources, not just those that the user is listed as an Owner, Contributor, or Viewer for.
          in: query
          name: public
          required: false
          type: string
      responses:
        "200":
          description: "200: Operation successful."
          headers:
            Last-Modified:
              description: The time that the item was last modified
              type: string
            dlx-continuation:
              description: A continuation token for retrieving more results
              type: string
            dlx-item-count:
              description: The number of items returned in the response
              type: string
      summary: Get all Lexemes for a Language
      tags:
        - Language
        - Lexeme
    post:
      operationId: addLexemeByLanguage
      parameters:
        - description: The ID of the Language to perform the operation on
          in: path
          name: languageID
          required: true
          type: string
      responses:
        "201":
          description: "201: The resource was created successfully."
          headers:
            Last-Modified:
              description: The time that the item was last modified
              type: string
      summary: Add a new Lexeme to a Language
      tags:
        - Language
        - Lexeme
    put:
      operationId: upsertLexemeByLanguage
      parameters:
        - description: The ID of the Language to perform the operation on
          in: path
          name: languageID
          required: true
          type: string
        - description: The `If-Match` header is used with PUT and DELETE requests to check whether you have the most up-to-date version of the resource before updating or deleting it. The value of the `If-Match` header is the ETag (`_etag`) property of the resource. It is recommended that your application use this header whenever possible to avoid data conflicts.
          in: header
          name: ifMatch
          required: false
          type: string
      responses:
        "201":
          description: "201: Upsert successful."
          headers:
            Last-Modified:
              description: The time that the item was last modified
              type: string
      summary: Upsert (add or replace) a Lexeme
      tags:
        - Language
        - Lexeme
  "/languages/{languageID}/lexemes/{lexemeID}":
    delete:
      operationId: deleteLexemeByLanguage
      parameters:
        - description: The ID of the Language to perform the operation on
          in: path
          name: languageID
          required: true
          type: string
        - description: The ID of the Lexeme to perform the operation on
          in: path
          name: lexemeID
          required: true
          type: string
        - description: The `If-Match` header is used with PUT and DELETE requests to check whether you have the most up-to-date version of the resource before updating or deleting it. The value of the `If-Match` header is the ETag (`_etag`) property of the resource. It is recommended that your application use this header whenever possible to avoid data conflicts.
          in: header
          name: ifMatch
          required: false
          type: string
      responses:
        "204":
          description: "204: Delete operation successful."
      summary: Delete a Lexeme by ID
      tags:
        - Language
        - Lexeme
    get:
      operationId: getLexemeByLanguage
      parameters:
        - description: The ID of the Language to perform the operation on
          in: path
          name: languageID
          required: true
          type: string
        - description: The ID of the Lexeme to perform the operation on
          in: path
          name: lexemeID
          required: true
          type: string
        - default: false
          description: Setting the `deleted` option to `true` will return results that have been marked for deletion, but not yet deleted from the database. Otherwise requests for a resource marked for deletion will return a 410 error.
          in: query
          name: deleted
          required: false
          type: boolean
        - description: If `If-None-Match` header is used with GET requests to check whether you already have the most up-to-date version of the resource, and therefore do not need the resource sent again. The value of the `If-None-Match` header is the ETag (`_etag`) property of the resource. It is recommended that your application use this header whenever possible to reduce bandwidth.
          in: header
          name: ifNoneMatch
          required: false
          type: string
      responses:
        "200":
          description: "200: Operation successful."
          headers:
            Last-Modified:
              description: The time that the item was last modified
              type: string
            dlx-continuation:
              description: A continuation token for retrieving more results
              type: string
            dlx-item-count:
              description: The number of items returned in the response
              type: string
        "304":
          description: "304: Not modified."
      summary: Get a Lexeme by ID
      tags:
        - Language
        - Lexeme
    patch:
      operationId: updateLexemeByLanguage
      parameters:
        - description: The ID of the Language to perform the operation on
          in: path
          name: languageID
          required: true
          type: string
        - description: The ID of the Lexeme to perform the operation on
          in: path
          name: lexemeID
          required: true
          type: string
        - description: The `If-Match` header is used with PUT and DELETE requests to check whether you have the most up-to-date version of the resource before updating or deleting it. The value of the `If-Match` header is the ETag (`_etag`) property of the resource. It is recommended that your application use this header whenever possible to avoid data conflicts.
          in: header
          name: ifMatch
          required: false
          type: string
      responses:
        "200":
          description: "200: Update successful."
          headers:
            Last-Modified:
              description: The time that the item was last modified
              type: string
      summary: Perform a partial update on a Lexeme
      tags:
        - Lexeme
  /lexemes:
    get:
      description: Retrieve all Lexemes that the authenticated user has permission to access. Include a `languageID` query parameter to limit results to Lexemes from a particular Language.
      operationId: getLexemes
      parameters:
        - description: The `dlx-continuation` header is used to send a continuation token with the request, when retrieving the next page of results.
          in: header
          name: continuation
          required: false
          type: string
        - default: false
          description: Setting the `deleted` option to `true` will return results that have been marked for deletion, but not yet deleted from the database. Otherwise requests for a resource marked for deletion will return a 410 error.
          in: query
          name: deleted
          required: false
          type: boolean
        - description: The `If-Modified-Since` header is used to retrieve only results modified since a given time. The value of this header must be a valid date string.
          in: header
          name: ifModifiedSince
          required: false
          type: string
        - allowEmptyValue: true
          description: The ID of the Language to perform the operation on
          in: query
          name: languageID
          required: false
          type: string
        - description: The `dlx-max-item-count` header is used to limit the number of results to a certain amount at a time (by default all results will be returned). If there are more results to be returned, a continuation token will also be sent in the `dlx-continuation` header.
          in: header
          name: maxItemCount
          required: false
          type: string
        - default: "false"
          description: Set this parameter to `true` to include all publicly-accessible resources, not just those that the user is listed as an Owner, Contributor, or Viewer for.
          in: query
          name: public
          required: false
          type: string
      responses:
        "200":
          description: "200: Operation successful."
          headers:
            Last-Modified:
              description: The time that the item was last modified
              type: string
            dlx-continuation:
              description: A continuation token for retrieving more results
              type: string
            dlx-item-count:
              description: The number of items returned in the response
              type: string
      summary: Get all Lexemes
      tags:
        - Lexeme
    post:
      description: Add a new Lexeme. A `languageID` must be provided either as a query parameter, or as an attribute on the Lexeme body.
      operationId: addLexeme
      parameters:
        - allowEmptyValue: true
          description: The ID of the Language to perform the operation on
          in: query
          name: languageID
          required: false
          type: string
      responses:
        "201":
          description: "201: The resource was created successfully."
          headers:
            Last-Modified:
              description: The time that the item was last modified
              type: string
      summary: Add a new Lexeme
      tags:
        - Lexeme
    put:
      description: Upsert (add or replace) a Lexeme. A `languageID` must be provided either as a query parameter, or as an attribute on the Lexeme body.
      operationId: upsertLexeme
      parameters:
        - description: The `If-Match` header is used with PUT and DELETE requests to check whether you have the most up-to-date version of the resource before updating or deleting it. The value of the `If-Match` header is the ETag (`_etag`) property of the resource. It is recommended that your application use this header whenever possible to avoid data conflicts.
          in: header
          name: ifMatch
          required: false
          type: string
        - allowEmptyValue: true
          description: The ID of the Language to perform the operation on
          in: query
          name: languageID
          required: false
          type: string
      responses:
        "201":
          description: "201: Upsert successful."
          headers:
            Last-Modified:
              description: The time that the item was last modified
              type: string
      summary: Upsert (add or replace) a Lexeme
      tags:
        - Lexeme
  "/lexemes/{lexemeID}":
    delete:
      operationId: deleteLexeme
      parameters:
        - description: The ID of the Lexeme to perform the operation on
          in: path
          name: lexemeID
          required: true
          type: string
        - description: The `If-Match` header is used with PUT and DELETE requests to check whether you have the most up-to-date version of the resource before updating or deleting it. The value of the `If-Match` header is the ETag (`_etag`) property of the resource. It is recommended that your application use this header whenever possible to avoid data conflicts.
          in: header
          name: ifMatch
          required: false
          type: string
      responses:
        "204":
          description: "204: Delete operation successful."
      summary: Delete a Lexeme by ID
      tags:
        - Lexeme
    get:
      operationId: getLexeme
      parameters:
        - description: The ID of the Lexeme to perform the operation on
          in: path
          name: lexemeID
          required: true
          type: string
        - default: false
          description: Setting the `deleted` option to `true` will return results that have been marked for deletion, but not yet deleted from the database. Otherwise requests for a resource marked for deletion will return a 410 error.
          in: query
          name: deleted
          required: false
          type: boolean
        - description: If `If-None-Match` header is used with GET requests to check whether you already have the most up-to-date version of the resource, and therefore do not need the resource sent again. The value of the `If-None-Match` header is the ETag (`_etag`) property of the resource. It is recommended that your application use this header whenever possible to reduce bandwidth.
          in: header
          name: ifNoneMatch
          required: false
          type: string
      responses:
        "200":
          description: "200: Operation successful."
          headers:
            Last-Modified:
              description: The time that the item was last modified
              type: string
            dlx-continuation:
              description: A continuation token for retrieving more results
              type: string
            dlx-item-count:
              description: The number of items returned in the response
              type: string
        "304":
          description: "304: Not modified."
      summary: Get a Lexeme by ID
      tags:
        - Lexeme
    patch:
      description: Perform a partial update on a Lexeme.
      operationId: updateLexeme
      parameters:
        - description: The ID of the Lexeme to perform the operation on
          in: path
          name: lexemeID
          required: true
          type: string
        - description: The `If-Match` header is used with PUT and DELETE requests to check whether you have the most up-to-date version of the resource before updating or deleting it. The value of the `If-Match` header is the ETag (`_etag`) property of the resource. It is recommended that your application use this header whenever possible to avoid data conflicts.
          in: header
          name: ifMatch
          required: false
          type: string
      responses:
        "200":
          description: "200: Update successful."
          headers:
            Last-Modified:
              description: The time that the item was last modified
              type: string
      summary: Perform a partial update on a Lexeme
      tags:
        - Lexeme
definitions: {}
