kick off development of spec

.github/workflows/lint.yml

@@ -0,0 +1,14 @@
+name: Run Spectral
+
+on: [push, pull_request]
+
+jobs:
+  lint:
+    name: Run Spectral
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+
+      - uses: stoplightio/spectral-action@master
+        with:
+          file_glob: "./DigitalOcean-public.v2.yaml"

.spectral.yml

@@ -0,0 +1,50 @@
+extends: [[spectral:oas, all]]
+rules:
+  contact-properties: off
+  operation-default-response: off
+
+  ratelimit-headers:
+    description: Response must include ratelimit-x headers
+    message: "{{description}}; missing {{property}}"
+    severity: error
+    given: $..responses.*
+    then:
+    - field: headers.ratelimit-limit
+      function: truthy
+    - field: headers.ratelimit-remaining
+      function: truthy
+    - field: headers.ratelimit-reset
+      function: truthy
+
+  properties-must-include-examples:
+    description: Object properties must include examples
+    message: "{{description}}; missing {{property}}"
+    severity: error
+    given: $..properties..properties.*
+    then:
+      field: example
+      function: schema
+      functionOptions:
+        schema:
+          minItems: 1
+
+  endpoint-must-be-ref:
+    description: Endpoint must a $ref
+    message: "{{description}}; {{property}} incorrect"
+    severity: error
+    resolved: false
+    given: $.paths.*
+    then:
+    - field: $ref
+      function: truthy
+
+  endpoint-ref-must-be-file:
+    description: Endpoint must a $ref to a file in endpoints/
+    message: "{{description}}; {{value}} incorrect"
+    severity: error
+    resolved: false
+    given: $.paths.*.$ref
+    then:
+      function: pattern
+      functionOptions:
+        match: "^endpoints\/.*yml$"

DigitalOcean-public.v2.yaml

@@ -0,0 +1,32 @@
+openapi: 3.0.0
+info:
+  title: DigitalOcean API
+  version: '2.0'
+  description: 'The DigitalOcean API allows you to manage Droplets and resources within the DigitalOcean cloud in a simple, programmatic way using conventional HTTP requests.'
+  license:
+    name: Apache 2.0
+    url: 'https://www.apache.org/licenses/LICENSE-2.0.html'
+  contact:
+    name: DigitalOcean API Team
+    email: api-engineering@digitalocean.com
+  termsOfService: 'https://www.digitalocean.com/legal/terms-of-service-agreement/'
+servers:
+  - url: 'https://api.digitalocean.com/v2'
+    description: production
+tags:
+  - name: Account
+    description: Provides information about your current account.
+  - name: SSH Keys
+    description: Manage SSH keys available on your account.
+paths:
+  /account:
+    $ref: 'endpoints/account.yml'
+  /account/keys:
+    $ref: 'endpoints/ssh_keys.yml'
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+security:
+  - bearerAuth: []

components/headers.yml

@@ -0,0 +1,25 @@
+ratelimit-limit:
+  schema:
+    type: integer
+    example: 5000
+  description: >-
+    The default limit on number of requests that can be made per hour and per minute.
+    Current rate limits are 5000 requests per hour and 250 requests per minute.
+
+ratelimit-remaining:
+  schema:
+    type: integer
+    example: 4816
+  description: >-
+    The number of requests in your hourly quota that remain before you hit your request limit.
+    See https://developers.digitalocean.com/documentation/v2/#rate-limit for information about
+    how requests expire.
+
+ratelimit-reset:
+  schema:
+    type: integer
+    example: 1444931833
+  description: >-
+    The time when the oldest request will expire. The value is given in Unix epoch time. 
+    See https://developers.digitalocean.com/documentation/v2/#rate-limit for information about
+    how requests expire.

components/parameters.yml

@@ -0,0 +1,22 @@
+PerPage:
+  in: query
+  name: per_page
+  required: false
+  description: Number of items returned per page
+  schema:
+    type: integer
+    minimum: 1
+    default: 20
+    maximum: 200
+    example: 2
+
+Page:
+  in: query
+  name: page
+  required: false
+  description: Which 'page' of paginated results to return.
+  schema:
+    type: integer
+    minimum: 1
+    default: 1
+    example: 1

components/schemas.yml

@@ -0,0 +1,112 @@
+WrappedAccount:
+  type: object
+  properties:
+    account:
+      $ref: '#/Account'
+  required:
+    - account
+
+Account:
+  type: object
+  properties:
+    droplet_limit:
+      description: The total number of Droplets current user or team may have active at one time.
+      type: integer
+      example: 25
+    floating_ip_limit:
+      description: The total number of Floating IPs the current user or team may have.
+      type: integer
+      example: 5
+    email:
+      description: The email address used by the current user to register for DigitalOcean.
+      type: string
+      example: sammy@digitalocean.com
+    uuid:
+      description: The unique universal identifier for the current user.
+      type: string
+      example: b6fr89dbf6d9156cace5f3c78dc9851d957381ef
+    email_verified:
+      description: If true, the user has verified their account via email. False otherwise.
+      type: boolean
+      default: false
+      example: true
+    status:
+      description: This value is one of "active", "warning" or "locked".
+      type: string
+      enum:
+        - active
+        - warning
+        - locked
+      default: active
+      example: active
+    status_message:
+      description: A human-readable message giving more details about the status of the account.
+      type: string
+      example: ""
+  required:
+    - droplet_limit
+    - floating_ip_limit
+    - email
+    - uuid
+    - email_verified
+    - status
+    - status_message
+
+DecoratedSSHKeys:
+  allOf:
+    - $ref: '#/WrappedSSHKeys'
+    - $ref: 'schemas/pages.yml#/Pagination'
+    - $ref: '#/Meta'
+
+WrappedSSHKeys:
+  type: object
+  properties:
+    ssh_keys:
+      type: array
+      items:
+        $ref: '#/SSHKeys'
+  required:
+    - ssh_keys
+
+SSHKeys:
+  type: object
+  properties:
+    id:
+      description: A unique identification number for this key. Can be used to embed a specific SSH key into a Droplet.
+      type: integer
+      example: 512189
+    fingerprint:
+      description: A unique identifier that differentiates this key from other keys using a format that SSH recognizes.
+      type: string
+      example: 3b:16:bf:e4:8b:00:8b:b8:59:8c:a9:d3:f0:19:45:fa
+    public_key:
+      description: >-
+        The entire public key string that was uploaded. Embedded into the root user's authorized_keys file 
+        if you include this key during Droplet creation.
+      type: string
+      example: "ssh-rsa AEXAMPLEaC1yc2EAAAADAQABAAAAQQDDHr/jh2Jy4yALcK4JyWbVkPRaWmhck3IgCoeOO3z1e2dBowLh64QAM+Qb72pxekALga2oi4GvT+TlWNhzPH4V example"
+    name:
+      description: A human-readable display name for this key, used to easily identify the SSH keys when they are displayed.
+      type: string
+      example: My SSH Public Key
+  required:
+    - id
+    - fingerprint
+    - public_key
+    - name
+
+Meta:
+  type: object
+  properties:
+    meta:
+      description: Information about the response itself.
+      type: object
+      properties:
+        total:
+          description: Number of objects returned by the request.
+          type: integer
+          example: 1
+      required:
+        - total
+  required:
+    - meta

components/schemas/pages.yml

@@ -0,0 +1,60 @@
+Pagination:
+  type: object
+  properties:
+    links:
+      $ref: '#/PageLinks'
+
+PageLinks:
+  type: object
+  properties:
+    pages:
+      anyOf:
+        - $ref: '#/ForwardLinks'
+        - $ref: '#/BackwardLinks'
+        - {}
+      example:
+        pages:
+          first: "https://api.digitalocean.com/v2/account/keys?page=1"
+          prev: "https://api.digitalocean.com/v2/account/keys?page=2"
+
+BackwardLinks:
+  allOf:
+    - $ref: '#/LinkToFirstPage'
+    - $ref: '#/LinkToPrevPage'
+
+ForwardLinks:
+  allOf:
+    - $ref: '#/LinkToLastPage'
+    - $ref: '#/LinkToNextPage'
+
+LinkToFirstPage:
+  type: object
+  properties:
+    first:
+      description: URI of the first page of the results.
+      type: string
+      example: "https://api.digitalocean.com/v2/images?page=1"
+
+LinkToPrevPage:
+  type: object
+  properties:
+    prev:
+      description: URI of the previous page of the results.
+      type: string
+      example: "https://api.digitalocean.com/v2/images?page=1"
+
+LinkToNextPage:
+  type: object
+  properties:
+    next:
+      description: URI of the next page of the results.
+      type: string
+      example: "https://api.digitalocean.com/v2/images?page=2"
+
+LinkToLastPage:
+  type: object
+  properties:
+    last:
+      description: URI of the last page of the results.
+      type: string
+      example: "https://api.digitalocean.com/v2/images?page=2"

endpoints/account.yml

@@ -0,0 +1,19 @@
+get:
+  description: To show information about the current user account, send a GET request to /account.
+  operationId: get_user_information
+  tags:
+    - Account
+  responses:
+    '200':
+      description: A JSON object keyed on account with an exerpt of the current user account data.
+      headers:
+        ratelimit-limit:
+          $ref: '../components/headers.yml#/ratelimit-limit'
+        ratelimit-remaining:
+          $ref: '../components/headers.yml#/ratelimit-remaining'
+        ratelimit-reset:
+          $ref: '../components/headers.yml#/ratelimit-reset'
+      content:
+        application/json:
+          schema:
+            $ref: '../components/schemas.yml#/WrappedAccount'