Merge pull request #2687 from SzySteve/docs/post_put_delete

Docs/post put delete

Author: Dorthu

docs/src/data/endpoints/account.yaml

@@ -97,11 +97,11 @@ endpoints:
                 -H "Authorization: Bearer $TOKEN" \
                 -X POST -d '{
                     "label": "Example app",
-                    "redirect_uri": "https://oauthreturn.example.org/",
+                    "redirect_uri": "https://example.org/oauth_callback/",
                 }' \
                 https://$api_root/$version/account/oauth-clients
           python: |
-            new_client = client.account.create_oauth_client('Example app', 'https://oauthreturn.example.org/')
+            new_client = client.account.create_oauth_client('Example app', 'https://example.org/oauth_callback/')
   /account/oauth-clients/$id:
     group: OAuth Clients
     type: resource
@@ -231,16 +231,20 @@ endpoints:
           username:
             type: String
             description: The username for the new user.
+            value: example_user
           email:
             type: String
             description: The user's email.
+            value: [email protected]
           password:
             type: String
             description: The user's password.
+            value: hunter2
           restricted:
-            optinoal: true
+            optional: true
             type: Boolean
             description: If false, this user has access to the entire account.  Defaults to true.
+            value: true
         examples:
           curl: |
             curl -H "Content-Type: application/json" \
@@ -374,27 +378,30 @@ endpoints:
         description: >
           Registers a new OAuth client application.
         params:
-          name:
+          label:
             description: A name for the new client application.
             type: string
             limit: "1-128 characters"
+            value: Example OAuth app
           redirect_uri:
             description: A URL to redirect to after the OAuth flow has completed.
             type: string
             limit: "1-512 characters"
+            value: https://example.org/oauth_callback/
           public:
             optional: true
             description: >
               If true, this client uses the implicit OAuth flow and does not
               use a client secret.
             type: Boolean
+            value: true
         examples:
           curl: |
             curl -H "Content-Type: application/json" \
                 -H "Authorization: Bearer $TOKEN" \
                 -X POST -d '{
                     "name": "Example app",
-                    "redirect_uri": "https://oauthreturn.example.org/",
+                    "redirect_uri": "https://example.org/oauth_callback/",
                 }' \
                 https://$api_root/$version/account/oauth-clients
   /account/oauth-clients/$id:
@@ -491,6 +498,7 @@ endpoints:
     group: Events
     type: resource
     authenticated: true
+    description: Updates marks all Events up to and including this Event as seen.
     methods:
       POST:
         description: >
@@ -504,6 +512,7 @@ endpoints:
     group: Events
     type: resource
     authenticated: true
+    description: Updates specific Event to designate that it has been read.
     methods:
       POST:
         description: >
@@ -571,15 +580,24 @@ endpoints:
             curl https://$api_root/$version/account/payments
       POST:
         oauth: account:modify
-        response: payment
         description: >
           Make a payment.
+        params:
+          usd:
+            type: String
+            description: The amount (in US Dollars) of the payment.
+            value: "120.00"
+          cvv:
+            type: String
+            optional: true
+            description: CVV (Card Verification Value) of the credit card to be used for the payment.
+            value: "0123"
         examples:
           curl: |
             curl -H "Content-Type: application/json" \
                 -H "Authorization: Bearer $TOKEN" \
                 -X POST -d '{
-                    "usd": 100,
+                    "usd": "120.00",
                 }' \
                 https://$api_root/$version/account/payments
   /account/payments/:id:

docs/src/data/endpoints/domains.yaml

@@ -41,6 +41,7 @@ endpoints:
             description: >
               Start of Authority (SOA) contact email.
             type: String
+            optional: true
           description:
             optional: true
             description: >
@@ -115,6 +116,8 @@ endpoints:
             import linode
             TODO
   /domains/$id:
+    description: >
+      Manage a particular Domain your account may access.
     authenticated: true
     methods:
       GET:
@@ -257,6 +260,8 @@ endpoints:
             TODO
   /domains/$id/records/$id:
     authenticated: true
+    description: >
+      Manage a particular Domain Record your account may access.
     methods:
       GET:
         response: domainrecord

docs/src/data/endpoints/networking.yaml

@@ -155,9 +155,11 @@ endpoints:
               address:
                 type: string
                 value: 210.111.22.94
+                description: IPv4 address to assign to a Linode.
               linode_id:
                 type: integer
                 value: 123405
+                description: The ID of the Linode to assign this address to.
         examples:
           curl: |
             curl -H "Content-Type: application/json" \

docs/src/data/endpoints/nodebalancers.yaml

@@ -125,13 +125,11 @@ endpoints:
         description: >
           Creates a NodeBalancer config.
         params:
-          label:
-            description: Unique label for your NodeBalancer config.
-            type: String
           port:
             description: Port to bind to on the public interfaces.
             limit: 1-65534
             type: Integer
+            optional: true
           protocol:
             description: The protocol used for the config.
             type: String

docs/src/data/endpoints/profile.yaml

@@ -266,14 +266,18 @@ endpoints:
               type: String
               description: >
                   The address, either v4 or v6, to allow logins from.
+              value: 123.45.67.89
             netmask:
               type: String
               description: >
                   If adding a v4 address, the netmask in the form of "255.255.255.0".
                   If adding a v6 address, the prefix length ('/64') as an integer.
+              value: 255.255.255.0
             note:
+              optional: true
               type: String
               description: A note to add alongside this entry.
+              value: home
           examples:
             curl: |
               curl -H "Authorization: Bearer $TOKEN" \

docs/src/data/endpoints/support.yaml

@@ -30,10 +30,12 @@ endpoints:
             description: >
               A short summary or title for the support ticket.
             type: String
+            value: A question about a Linode
           description:
             description: >
               The complete details of the support request.
             type: String
+            value: More details about the question
           domain_id:
             description: >
               The Domain this ticket is regarding, if relevant.
@@ -44,6 +46,7 @@ endpoints:
               The Linode this ticket is regarding, if relevant.
             type: Integer
             optional: true
+            value: 123
           longviewclient_id:
             description: >
               The LongviewClient this ticket is regarding, if relevant.
@@ -54,6 +57,11 @@ endpoints:
               The NodeBalancer this ticket is regarding, if relevant.
             type: Integer
             optional: true
+          volume_id:
+            description: >
+              The Block Storage Volume this ticket is regarding, if relevant.
+            type: Integer
+            optional: true
         examples:
           curl: |
             curl -H "Content-Type: application/json" \

docs/src/data/objects/oauthclient.yaml

@@ -19,7 +19,7 @@ schema:
     description: The app's client secret, used in the OAuth flow. Visible only on app creation.
   redirect_uri:
     type: String
-    value: https://oauthreturn.example.org/
+    value: https://example.org/oauth_callback
     description: The URL to redirect to after the OAuth flow.
     limit: 1-512 characters
     editable: true