dnsimple / dnsimple-developer Goto Github PK

This appears to be used only when attempting to enable vanity codes but they're not enabled for the current plan. Code's not mentioned in https://developer.dnsimple.com/v2/#response-codes.

Something confusing related to this is that enabling vanity servers when plan doesn't support it returns 412 with this response:

{
  "message": "Feature not enabled: vanity_name_servers"
}

But attempting to set regions on a record when plan doesn't support it returns 400 with this response:

{
  "message": "Regions are not allowed for your plan.",
  "errors": {}
}

The inconsistent error codes make it difficult to handle a "feature not enabled" response from the server. Sorry I know this isn't documentation related but not sure where it's best to bring it up. Having a different code from 400 (which I read as being invalid JSON input in the request body) would be useful.

https://github.com/dnsimple/dnsimple-developer/blob/master/content/v1/domains/records.markdown list "name" and "type" as parameters for GET /domains/:domain/records, but that does not make sense. Only ":domain" is required for listing records.

Documentation for POST and PATCH actions include a section to display an example of a JSON payload. We have to complete that section in several places:

• Domain.create
• EmailForward.create
• VanityNameServers.delegate
• Contacts.create
• ZoneRecords.create #68
• ZoneRecords.update #68
• TemplateRecords.create

This is a place to discuss the structure for API v2

In API v1, we have the following:

• Overview
  • Authentication
• Domains
  • Records
  • Sharing
  • Email Forwards
  • Zones
• Registration
  • Prices
  • Auto Renewal
  • WHOIS Privacy
  • Extended Attributes
• Name Servers
  • Vanity Name Servers
• SSL Certificates
• Contacts
• Services
  • Domain Services
• Templates
  • Records
  • Domain Templates
• Users
• Subscriptions

Categories that include nested operations that may need to live at their own level, but which do not in V1, include:

• Domains defines operations for domain CRUD as well as reset domain token and push a domain.
• Registration defines operations for register, transfer, renew, transfer out and check domain availability.
• Name Servers defines both operations on domain name servers as well as operations to register and de-register name servers at the registry.
• Domain Services covers applied and available services, as well as applying and unapplying a service
• Domain Templates covers applying a template

Gabriel

Now v2 is GA and the API is stable, it would be great to enhance the documentation a bit.

In many cases it's unclear whether a returned value could be null or not, and the type of data returned is not specified. It can be inferred from the example fixture, but they don't cover all cases - for example, on the Zone Records page you need to look at a couple of fixtures to know that priority is expected to be either an integer or null.

JSON Schema seems like a logical way to document these and something than is both human and machine readable. While this could be specified for GET, POST and PATCH requests, I think it's most valuable for GET, since the inputs for POST and PATCH are already well defined in the documentation.

There are lots of ways to play with this, but at a minimum I'd want to see definitions for each of the possible return types (like a zone record, a domain, etc).

For a zone record, it would be something like:

{
  "$schema":"http://json-schema.org/draft-04/schema#",
  "type":"object",
  "oneOf":[
    {
      "properties":{
        "type":{
          "enum":[
            "MX"
          ]
        },
        "priority":{
          "type":"integer"
        }
      }
    },
    {
      "properties":{
        "type":{
          "not":{
            "enum":[
              "MX"
            ]
          }
        },
        "priority":{
          "type":"null"
        }
      }
    }
  ],
  "properties":{
    "type":{
      "type":"string"
    },
    "priority":{
      "type":[
        "null",
        "integer"
      ]
    },
    "id":{
      "type":"integer"
    },
    "zone_id":{
      "type":"string"
    },
    "parent_id":{
      "type":[
        "string",
        "null"
      ]
    },
    "name":{
      "type":"string"
    },
    "content":{
      "type":"string"
    },
    "ttl":{
      "type":"integer"
    },
    "regions":{
      "type":"array",
      "minItems":1,
      "uniqueItems":true,
      "oneOf":[
        {
          "items":{
            "enum":[
              "SV1",
              "ORD",
              "IAD",
              "AMS",
              "TKO"
            ]
          }
        },
        {
          "items":{
            "enum":[
              "global"
            ]
          }
        }
      ]
    },
    "system_record":{
      "type":"boolean"
    },
    "created_at":{
      "type":"string",
      "format":"date-time"
    },
    "updated_at":{
      "type":"string",
      "format":"date-time"
    }
  }
}

A reasonably strict example for "List records for a zone" endpoint might look like this (this is valid), but doing this for every endpoint is a more tedious task that coming up with schemas for the objects themselves:

{
  "$schema":"http://json-schema.org/draft-04/schema#",
  "type":"object",
  "properties":{
    "data":{
      "type":"array",
      "items":{
        "$ref":"#/definitions/zone_record"
      }
    },
    "pagination":{
      "$ref":"#/definitions/pagination"
    }
  },
  "definitions":{
    "zone_record":{
      "oneOf":[
        {
          "properties":{
            "type":{
              "enum":[
                "MX"
              ]
            },
            "priority":{
              "type":"integer"
            }
          }
        },
        {
          "properties":{
            "type":{
              "not":{
                "enum":[
                  "MX"
                ]
              }
            },
            "priority":{
              "type":"null"
            }
          }
        }
      ],
      "type":"object",
      "properties":{
        "type":{
          "type":"string"
        },
        "priority":{
          "type":[
            "null",
            "integer"
          ]
        },
        "id":{
          "type":"integer"
        },
        "zone_id":{
          "type":"string"
        },
        "parent_id":{
          "type":[
            "string",
            "null"
          ]
        },
        "name":{
          "type":"string"
        },
        "content":{
          "type":"string"
        },
        "ttl":{
          "type":"integer"
        },
        "regions":{
          "type":"array",
          "minItems":1,
          "uniqueItems":true,
          "oneOf":[
            {
              "items":{
                "enum":[
                  "SV1",
                  "ORD",
                  "IAD",
                  "AMS",
                  "TKO"
                ]
              }
            },
            {
              "items":{
                "enum":[
                  "global"
                ]
              }
            }
          ]
        },
        "system_record":{
          "type":"boolean"
        },
        "created_at":{
          "type":"string",
          "format":"date-time"
        },
        "updated_at":{
          "type":"string",
          "format":"date-time"
        }
      }
    },
    "pagination":{
      "type":"object",
      "properties":{
        "current_page":{
          "type":"integer"
        },
        "per_page":{
          "type":"integer"
        },
        "total_entries":{
          "type":"integer"
        },
        "total_pages":{
          "type":"integer"
        }
      }
    }
  }
}

The webhooks details page at the moment does not include examples from the different actors or the data that we send along with it.

User story:

As a customer and API integrator
I want to know how webhooks looks like and have all relevant information about webhook data at a single spot
In order to be sure what data to expect from a hook

The example return for https://dnsimple.com/domains doesn't match what the API returns. It's missing {} around the dicts.

Add support for https://developer.dnsimple.com/v2/domains/collaborators/

Clients

• Elixir
• Go
• Node (dnsimple/dnsimple-node#4)
• Ruby

In https://developer.dnsimple.com/sandbox/#getting-started there is a steps that reads:

When asked to choose a plan choose Skip this step and choose a plan later at the bottom. If you want to test features that requires a valid subscription, including registering test domains, please refer to the Testing Subscriptions section.

This is not this way anymore, so it might be adjusted.

In mobile applications it is not possible to keep an OAuth client secret a secret, as it must be hardcoded into the application code. It is trivial to extract hard coded strings from a mobile application.

The draft DNSimple v2 OAuth documentation says "The client secret should not be shared." Given this is impossible for a mobile application, does the DNSimple OAuth implementation prevent supporting a mobile application? Or does the word "should" mean this is a recommendation that can be ignored for mobile apps?

Interested to know how the official iOS DNSimple app might change it's authentication flow for v2 as well.

Thanks!

The section http://developer.dnsimple.com/v1/#current-version is missing the expiration year for v0.

The legacy API (called v0) will no longer be available after June 30th. Please switch to API v1 as soon as possible. Read the versioned API announcement for more details.

Add the expiration year after June 30th.

Is this correct for purchasing / registering a domain?

I get the response of: {"message":"Validation failed"}

curl -H 'Authorization: Bearer '$apiv2token -H 'Accept: application/json' -H 'Content-Type: application/json' -X POST -d '{"registrant_id": 72624, "whois_privacy":false, "auto_renew": true, "premium_price": false,"extended_attributes":"com", "premium_price":null}' https://api.dnsimple.com/v2/$acctId/registrar/domains/mydomain.com/registrations

https://developer.dnsimple.com/v2/services/domains/#unapply

• It looks like the response of the list contains a v1 serialized response (notice the service node)
• The unapply docs seems to be copied from v1 and not updated for v2

/cc @jodosha @jacegu

• https://developer.dnsimple.com/v2/zones/records/ (#68)
• https://developer.dnsimple.com/v2/services/ (#65)
• https://developer.dnsimple.com/v2/templates/ (bd16a14 and 0996fb4)
• https://developer.dnsimple.com/v2/templates/records/ (#67)
• https://developer.dnsimple.com/v2/vanity/

Store the PDF in this repo instead of via tweets.
https://twitter.com/CodeStars/status/845932130958032896

We need to document the various concepts that exist in DNSimple so that developers can understand what entities are available to them from our system.

Docs

• developer reference

Clients

• Elixir (dnsimple/dnsimple-elixir#94)
• Go (dnsimple/dnsimple-go@19eb766)
• Node
• Ruby (dnsimple/dnsimple-ruby#141)

We should release a new mini version (or major) for every single library version.

Clients

• Elixir (dnsimple/dnsimple-elixir@3810465)
• Go (dnsimple/dnsimple-go@d1105ab)
• Node
• Ruby

The API support CORS. CORS is used to allow AJAX cross-site requests and should be documented on the developer site.

JavaScript library references CORS: https://github.com/aetrion/dnsimple-js

See

• https://www.intercom.io/apps/m45hdo0v/messages/86063/message_threads/132942
• https://www.pivotaltracker.com/story/show/38002879

The sandbox documentation at https://developer.dnsimple.com/sandbox/ is not clear on the purpose and value of the sandbox. This documentation needs to be updated to clarify why the sandbox is useful and how it should be used.

Hi,

I'm getting this error when using the API to check for domain availability:

SSL certificate problem: self signed certificate in certificate chain

How do I fix this?

Thanks

Followed the instructions documention for the vanity_name_servers endpoint, and even by copying and pasting the sample code, the respone from the endpoint is:

{
    "errors": [
        "Feature not enabled"
    ]
}

If the feature is not yet enabled, it would be great to document that. If it is enabled, would be great to update the sample code. The response code is HTTP/1.1 400 Bad Request.

Before the release, we should make sure that all the clients uses the same (and latest) version of the fixtures.

Ideally, we should have a task in each single repo that pulls the entire fixture folder and replaces the one in the client repo.

Clients

• Elixir (dnsimple/dnsimple-elixir#85)
• Go
• Node
• Ruby (dnsimple/dnsimple-ruby#142)

The current view we provide in the developer documentation is a good reference, however I would like to add an additional section that describes the various ways customers may use the API.

When sending an invalid request to create a new record, we might get an "errors" element in the JSON response:

{
  "message": "Validation failed",
  "errors": {
    "record_type": [
      "can't be blank",
      "unsupported"
    ],
    "name": [
      "must be valid"
    ],
    "content": [
      "can't be blank"
    ]
  }
}

The "errors" element isn't documented. Appears to be field level validation, but it's not clear which endpoints will return this, and the format isn't specified in the documentation.

Simply adding a domain hosted with another registrar is not listed in the API docs — That is, without registering/transferring a domain to Dnsimple.

Update the registrar methods to use the new URLs we decided to adopt before API v2 GA, and not the old one (singular routes).

See for reference:

• https://developer.dnsimple.com/v2/registrar/

Clients:

• Ruby: dnsimple/dnsimple-ruby#153 / v4.3.0
• Go: dnsimple/dnsimple-go#59
• Elixir: dnsimple/dnsimple-elixir#112 / v1.1.1
• Node: dnsimple/dnsimple-node#12
• Java: dnsimple/dnsimple-java#5

If I understood it correctly then listZoneRecords should return all records per zone, but in the following example it lists two zones: zone_id: "example.com" and zone_id: "example-1458642023.com".

Bring from the support site:

• A label that identifies the site as "developer".
• Typography: font-stack, styles.
• Colors
• Categories list on the left.
• High-res logo.

Reading trough the Sandbox documentation I found the following statement:

This site is generally an exact duplicate of the production application [...]

it would be helpful to call the user to create a account, and make it clear that the data is not synced in any way. (That was at least my first impression)

Running rake test doesn't check all articles. We need to recursively iterate over the content folder. We currently use Dir["content/*"].each do |path| on _test/content_test.rb

Related to dnsimple/dnsimple-support#529

Need sdks for several languages you don't have. Just want to recommend moving to swagger in case it's not been discussed yet.

I was not able to figure out what this API field actually is. Adding a description (and more meaningful examples as null) would be helpful :)

Document the use of the domain token for authentication.

Currently the docs say:

Responding to Webhooks

To confirm receipt of a webhook, your server must respond with an HTTP 200 response. Any other response will be considered an error and may cause the event to be retried.

I think it would be more precise if a web hook is retried or not. may may be problematic ;)

The response of the register, transfer and renew commands was changed (to support async tasks). All the clients must be updated, and the developer referenced updated accordingly.

Docs

• developer reference

Clients

• Elixir (dnsimple/dnsimple-elixir#88)
• Go (dnsimple/dnsimple-go#52)
• Node
• Ruby (dnsimple/dnsimple-ruby#140)

There is a method to add a subscription or get its details, but I miss one to get available plans to use. For example GET /plans and GET /plans/:name

{ "name": "Platinum",
  "price": 50,
  "domains": 500,
  "domain_price": 0.1 }

API documented in #142

• Ruby dnsimple/dnsimple-ruby#152
• Go dnsimple/dnsimple-go#58
• Elixir dnsimple/dnsimple-elixir#108
• Node dnsimple/dnsimple-node#10

It now includes a DNSimple driver.

According to RFC 6749 "state" is only used in authorization request and authorization response. However in the DNSimple implementation (in the sandbox at any rate) it's required at step 2 as a POST parameter. This isn't in compliance with the spec, and also isn't documented in the DNSimple docs.

It would be cool if we could show the API version like this:

Thoughts?

Request for this to be implemented in the API:

the client will be able to negotiate an access token by sending a request authenticated using the basic auth and account username/password, along with the necessary OTP token (if the account is protected via 2FA).

Refer #49 (comment).

Doc says PUT /:account/domains/:domain/name_servers but the curl sample uses POST

In https://github.com/aetrion/dnsimple-developer/blob/master/content/v2/domains/name-servers.markdown

Docs

• developer reference (#105)

Clients

• Elixir (dnsimple/dnsimple-elixir#87)
• Go (dnsimple/dnsimple-go#53)
• Node (dnsimple/dnsimple-node#5)
• Ruby (dnsimple/dnsimple-ruby#143)

http://developer.dnsimple.com/domains/certificates/#purchase-a-certificate
The documentation should include the wants_csr param documentation.