{"version"=>1, "root"=>"/api/v1", "endpoints"=>{""=>{"description"=>"The root of the API service.", "methods"=>{"GET"=>{"description"=>"Provide introspection for the available API endpoints.", "returns"=>{"a_data_structure"=>"You're looking at it!"}}}}, "availability"=>{"description"=>"Account availability status.", "methods"=>{"GET"=>{"description"=>"Check if an account name is currently available for registration.", "parameters"=>{"required"=>{"account"=>"An account name."}}, "returns"=>{"available"=>"The account's current availability as a boolean."}}}}, "challenge"=>{"description"=>"Authentication tokens.", "methods"=>{"GET"=>{"description"=>"Fetch a new authentication challenge.", "returns"=>{"challenge"=>"The challenge token."}}}}, "ip"=>{"description"=>"Retreive IP address information.", "methods"=>{"GET"=>{"description"=>"Return your current IPv4 address, as the server sees it.", "returns"=>{"ip"=>"Your IPv4 address."}}}}, "accounts"=>{"description"=>"Account listings.", "admin_required"=>true, "methods"=>{"GET"=>{"multiple_response"=>true, "description"=>"Fetch all accounts.", "returns"=>{"name"=>"The unique username of the account.", "email"=>"The email address linked to the account.", "givenname"=>"The first name provided at signup time.", "surname"=>"The last name provided at signup, if any.", "date_signup"=>"The date and time the account was created.", "date_signup_approx"=>"A timespan description of date_signup, in English.", "date_modified"=>"The date and time the account last altered its records.", "date_modified_approx"=>"A timespan description of date_modified, in English.", "signup_ip"=>"The IP address used to register the account.", "active"=>"Boolean true if the account has modified records within the configured deactivation timespan.", "admin"=>"Boolean true if the account is marked as an administrator.", "immortal"=>"Boolean true if the account is marked as immortal. Immortal accounts aren't deactivated or removed for inactivity.", "locked"=>"Boolean true if the account is marked as locked, which is a state usually reserved for abusive or otherwise disabled accounts.  Locked accounts are unable to login or change any state.", "verified"=>"Boolean true if the email address has been validated by a human."}}}}, "accounts/[name]"=>{"description"=>"Individual account management.", "auth_required"=>true, "methods"=>{"GET"=>{"description"=>"Fetch a specific account.  Unless the authenticated account is an administrator, the account being fetched must match the account currently authed.", "returns"=>{"name"=>"The unique username of the account.", "email"=>"The email address linked to the account.", "givenname"=>"The first name provided at signup time.", "surname"=>"The last name provided at signup, if any.", "date_signup"=>"The date and time the account was created.", "date_signup_approx"=>"A timespan description of date_signup, in English.", "date_modified"=>"The date and time the account last altered its records.", "date_modified_approx"=>"A timespan description of date_modified, in English.", "active"=>"Boolean true if the account has modified records within the configured deactivation timespan.", "admin"=>"Boolean true if the account is marked as an administrator.", "immortal"=>"Boolean true if the account is marked as immortal. Immortal accounts aren't deactivated or removed for inactivity.", "locked"=>"Boolean true if the account is marked as locked, which is a state usually reserved for abusive or otherwise disabled accounts.  Locked accounts are unable to login or change any state.", "verified"=>"Boolean true if the email address has been validated by a human."}}, "PUT"=>{"description"=>"Modify an existing account.  Permissions are fine-grained, and behavior differs between parameters.", "parameters"=>{"optional"=>{"email"=>"Alter the linked email address for the account.  This does NOT immediately change the email, but instead triggers a validation request to the new email address.", "givenname"=>"Alter the first name on the account.  Only used for display. Authenticated account must be an administrator.", "surname"=>"Alter the last name on the account.  Only used for display. Authenticated account must be an administrator.", "password"=>"Change the account password.", "active"=>"Boolean, set whether the account will be included in active DNS. This is normally adjusted automatically on record update activity. Authenticated account must be an administrator.", "immortal"=>"Boolean, removes an account from deactivation and expiration activity timers. Authenticated account must be an administrator.", "locked"=>"Boolean, freezes the state of the account and records under it. The account will be unable to login. Authenticated account must be an administrator."}}}, "DELETE"=>{"description"=>"Remove a specific account.  The authenticated account must be an administrator.", "parameters"=>{"required"=>{"reason"=>"Audit trail, a description of why the account was deleted."}}}}}, "records"=>{"description"=>"DNS record creation and listings.", "auth_required"=>true, "methods"=>{"GET"=>{"multiple_response"=>true, "description"=>"Fetch all records for the authenticated account.", "returns"=>{"id"=>"The unique identifier for this record.", "type"=>"The DNS record type. (Either 'A' or 'NS'.)", "ip"=>"An IPv4 address this record resolves to.", "subdomain"=>"If this exists, the record is a subdomain under the authenticated account namespace.  If it does not, the record refers to the top-level DNS namespace.", "active"=>"Boolean true if the record is resolvable via DNS.", "wildcard"=>"Boolean true if the record's namespace is wildcarded."}}, "POST"=>{"description"=>"Create a new DNS record.  The URI can be found in the response Location header.", "parameters"=>{"required"=>{"ip"=>"An IPv4 address this record will resolve to."}, "optional"=>{"account"=>"Create this record on behalf of an account other than the currently authed one.  Requires administrator credentials.", "active"=>"Boolean, set whether this record will be immediately resolvable via DNS.  Defaults to 'true'.", "subdomain"=>"A hostname, marking this record as a subdomain under the account namespace.  The record defaults to the top-level (account name) namespace.", "type"=>"A string specifying the DNS record type.  Either 'A\" or 'NS', currently.  Defaults to 'A'.", "wildcard"=>"Boolean, set the DNS namespace of the record to be wildcarded for all subdomain queries."}}}}}, "records/[id]"=>{"description"=>"Individual DNS record management.", "auth_required"=>true, "methods"=>{"GET"=>{"description"=>"Fetch a specific record.", "returns"=>{"id"=>"The unique identifier for this record.", "type"=>"The DNS record type. (Either 'A' or 'NS'.)", "ip"=>"An IPv4 address this record resolves to.", "subdomain"=>"If this exists, the record is a subdomain under the authenticated account namespace.  If it does not, the record refers to the top-level DNS namespace.", "active"=>"Boolean true if the record is resolvable via DNS.", "wildcard"=>"Boolean true if the record's namespace is wildcarded."}}, "PUT"=>{"description"=>"Modify an existing DNS record.", "parameters"=>{"optional"=>{"ip"=>"An IPv4 address the record will resolve to.", "active"=>"Boolean, set whether the record will be immediately resolvable via DNS.", "subdomain"=>"A hostname, marking the record as a subdomain under the account namespace.  Setting to '-' places it within the top-level (account name) namespace.", "type"=>"A string specifying the DNS record type.  Either 'A\" or 'NS', currently.", "wildcard"=>"Boolean, set the DNS namespace of the record to be wildcarded for all subdomain queries."}}}, "DELETE"=>{"description"=>"Remove a record."}}}, "resend-validation"=>{"description"=>"Sends the account's unique validation link via email.", "auth_required"=>true, "methods"=>{"POST"=>{"description"=>"Resend the original validation email to the signup address.  There is no 'Location' header nor body in the return.  A successful send will reply with a 204 (NO_CONTENT) status."}}}, "reset-password"=>{"description"=>"Generate and send a password reset link to an account.", "auth_required"=>false, "methods"=>{"POST"=>{"description"=>"Create a new, limited time link that allows a password reset, sending it immediately to the specified account.  There is no 'Location' header nor body in the return.  A successful send will reply with a 204 (NO_CONTENT) status.", "parameters"=>{"required"=>{"account"=>"The account name."}}}}}, "session"=>{"description"=>"Session management.", "auth_required"=>false, "methods"=>{"POST"=>{"description"=>"Create a new session.", "parameters"=>{"required"=>{"account"=>"The account name.", "challenge"=>"A challenge token.", "response"=>"A valid response to the challenge."}}, "returns"=>{"session"=>"The session ID key, to be used in the 'sc-session' cookie."}}, "DELETE"=>{"description"=>"Remove a currently active session.", "returns"=>{"session"=>"The deleted session ID key."}}}}, "stats"=>{"description"=>"Various account statistics.", "auth_required"=>true, "methods"=>{"GET"=>{"description"=>"Generate an array of data points over the last 30 days, describing various pieces of account activity. Currently, only recent DNS activity is returned.", "returns"=>{"dns_activity"=>"An array of DNS lookups per hour.  Times are in milliseconds since the epoch (suitable for javascript date objects.)"}}}}}}