An attempt to standardize the Standard Files API (OpenAPI3)

standard_files.yml

openapi: 3.0.0
info:
  version: "1.0.0"
  title: "Standard File"
  license:
    name: "Apache 2.0"
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"
servers:
  - url: https://app.standardnotes.org/

tags:
- name: "auth"
- name: "items"

paths:
  /auth:
    post:
      tags:
      - "auth"
      summary: "Registers a user and returns a JWT"
      operationId: authReg
      parameters:
      - name: email
        in: query
        required: true
        schema:
          $ref: '#/components/schemas/User/properties/email'
      - name: password
        in: query
        required: true
        schema:
          $ref: '#/components/schemas/User/properties/password'
      - name: pw_cost
        in: query
        required: true
        schema:
          $ref: '#/components/schemas/User/properties/pw_cost'
      - name: pw_nonce
        in: query
        required: true
        schema:
          $ref: '#/components/schemas/User/properties/pw_nonce'
      - name: version
        in: query
        schema:
          $ref: '#/components/schemas/User/properties/version'
      responses:
        200:
          $ref: '#/components/responses/Token'
        default:
          $ref: '#/components/responses/Error'

  /auth/change_pw:
    post:
      tags:
      - "auth"
      summary: "Updates a user's password"
      operationId: authChangePw
      parameters:
      - name: email
        in: query
        required: true
        schema:
          $ref: '#/components/schemas/User/properties/email'
      - name: password
        in: query
        required: true
        schema:
          $ref: '#/components/schemas/User/properties/password'
      - name: current_password
        in: query
        required: true
        schema:
          $ref: '#/components/schemas/User/properties/password'
      responses:
        204:
          description: No Content
        default:
          $ref: '#/components/responses/Error'

  /auth/sign_in:
    post:
      tags:
      - "auth"
      summary: "Authenticates a user and returns a JWT"
      operationId: authSignIn
      parameters:
      - name: email
        in: query
        required: true
        schema:
          $ref: '#/components/schemas/User/properties/email'
      - name: password
        in: query
        required: true
        schema:
          $ref: '#/components/schemas/User/properties/password'
      responses:
        200:
          $ref: '#/components/responses/Token'
        default:
          $ref: '#/components/responses/Error'

  /auth/update:
    post:
      tags:
      - "auth"
      operationId: authUpdate
      parameters:
      - name: pw_cost
        in: query
        schema:
          $ref: '#/components/schemas/User/properties/pw_cost'
      - name: pw_nonce
        in: query
        schema:
          $ref: '#/components/schemas/User/properties/pw_nonce'
      - name: version
        in: query
        schema:
          $ref: '#/components/schemas/User/properties/version'
      responses:
        200:
          description: Unknown Output
        default:
          $ref: '#/components/responses/Error'

  /auth/params:
    get:
      tags:
      - "auth"
      summary: "Returns the parameters used for password generation"
      operationId: authParams
      parameters:
      - name: email
        in: query
        required: true
        schema:
          $ref: '#/components/schemas/User/properties/email'
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  pw_cost:
                    type: string
                  pw_nonce:
                    type: string
                  version:
                    type: string
        default:
          $ref: '#/components/responses/Error'

  /items:
    post:
      tags:
      - "items"
      operationId: itemCreate
      responses:
        200:
          description: Unknown Output
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    delete:
      tags:
      - "items"
      operationId: itemDestroy
      responses:
        200:
          description: Unknown Output
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []

  /items/sync:
    post:
      tags:
      - "items"
      summary: Saves local changes as well as retrieves remote changes
      operationId: itemSync
      parameters:
      - name: items
        in: query
        description: An array of items
        required: true
        schema:
          type: array
          items:
            $ref: '#/components/schemas/Item'
      - name: sync_token
        in: query
        description: The sync token returned from the previous sync call
        schema:
          type: string
      - name: limit
        in: query
        description: The number of results to return. `cursor_token` is returned if more results are available
        schema:
          type: integer
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  retrieved_items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Item'
                  saved_items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Item'
                  unsaved:
                    type: array
                    items:
                      $ref: '#/components/schemas/Item'
                  sync_token:
                    type: string
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []

  /items/backup:
    post:
      tags:
      - "items"
      summary: Writes all user data to backup extension
      description: This is called when a new extension is registered
      operationId: itemBackup
      responses:
        200:
          description: Unknown Output
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []

  /items/{uuid}:
    delete:
      tags:
      - "items"
      operationId: itemDeleteId
      parameters:
      - name: uuid
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/Item/properties/uuid'
      responses:
        200:
          description: Unknown Output
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []

components:
  responses:
    Token:
      description: JWT Token
      content:
        application/json:
          schema:
            type: object
            properties:
              token:
                type: string

    Error:
      description: Unexpected Error
      content:
        application/json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  type: string

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    User:
      type: object
      properties:
        email:
          type: string
          format: email
          description: The email of the user
        password:
          type: string
          format: password
          description: The *encrypted* password for this user (encryption happens before being sent to server)
        pw_cost:
          type: string
          description: The number of iterations to use for the KDF
        pw_nonce:
          type: string
          description: Generated by the client during registration
        version:
          type: string
          default: '003'
          description: The version of the SF specification used when creating this user's account (This value is also updated when a user changes their password or updates their security version.)

    Item:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
          description: The unique identifier for this model
        content:
          type: string
          format: byte
          description: The *encrypted* JSON encoded structure of the item
        content_type:
          type: string
          description: The type of the structure contained in the content field (i.e Note, Tag, Extension, etc.)
        enc_item_key:
          type: string
          format: text
          description: The locally encrypted encryption key for this item
        deleted:
          type: boolean
          description: Whether the model has been deleted
        created_at:
          type: string
          format: date-time
          description: The date this item was created
        updated_at:
          type: string
          format: date-time
          description: The date this item was last modified