Why is the cloudflare API such a dumpster fire of inconsistency?
I wanted to create a script that will walk the entire API and hit every 'GET' method endpoint as a means of creating a complete snapshot of an entire account. there are many "backup" scripts out there, but all are limited in scope, and dont support grabbing "everything". ideally i would have done this programmatically by using the schema file (obtained from webui or github), but that doesnt even validate with openapi standards.
spending some time on the API documentation site i soon realized that im going to literally have to build this script in the most manual process, by looking at each and every GET endpoint, then trying to make sense of what values ill need to populate into the url.
identifiers. terribly inconsistent.
/zones/{identifier}
/zones/{zone_identifier}
/zones/{zone_id}
/zones/{zoneId}
/zones/{zone}
all of those refer to the same value.
/accounts/{account_identifier}
/accounts/{account_id}
/accounts/{identifier}
/accounts/{account}
/accounts/{accountId}
honestly this is piss poor.
some endpoints refer to {identifier} and the actual value name is 'tag'.
heres a hint:
use the parent name in the path in its singular form, and then use the actual name if you need to reference it.
a perfect example of this is:
/zones/{zone_id}/rulesets/{ruleset_id}
if the value name in a ruleset thats used as its 'identifier' named 'tag', then ffs use:
/zones/{zone_id}/rulesets/{ruleset_tag}
referring to it as simply {identifier} when the actual value name seems to be anything, helps no one.
this way even if your schema file doesnt validate, like it doesnt at the time of me writing this, i could at least count on knowing what value i need to get from each item returned when i get the parent endpoint just by using the name after the underscore. but instead you force me to have to click around on the api doc site to try and track down every value.
oh, and there are some references to 'identifiers' that dont even exist in said item... so thanks for that :/
11 Replies
You should use feedback button in the bottom left corner on the api docs site as it is routed to the api team
ack, ty
We’ve been raising issues like this for >12 months unfortunately with very little progress or change.
I really hope this is something Cloudflare focus on in the near future.
Also cc @jb, this is good feedback
the values you've mentioned are all the same regardless of what the example URLs use. the difference is that during the migration we haven't enforced a convention however, that is already fixed for newer endpoints. the older ones still need the teams to update them.
as for not validating against the openapi specification, that is still intentional since we migrated from an alternative schema format that didn't have a standard and we still have teams making the move. this is already underway but is a longer term effort.
the values i mentioned are all the same only in the fact that the api is calling them an 'identifier', but the actual name of the value can be anything from 'id' to 'name' to 'tag'. . as i mentioned, referring to the value needed for the query as simply 'identifier' is completely useless. it forces the user to have to look through the docs to try and find the name of the actual value they need to use. this is incredibly annoying and an astounding waste of time.
also... https://developers.cloudflare.com/api/operations/registrar-domains-list-domains returns an aray of objects, except, going by the documentation, is missing probably the most important value. "name" or "domain_name". i dont think its unreasonable when asking for a list of registered domains, that the actual domain name would be included in the results.
{
"errors": [],
"messages": [],
"result": [
{
"available": false,
"can_register": false,
"created_at": "2018-08-28T17:26:26Z",
"current_registrar": "Cloudflare",
"expires_at": "2019-08-28T23:59:59Z",
"id": "ea95132c15732412d22c1476fa83f27a",
"locked": false,
"registrant_contact": {
"address": "123 Sesame St.",
"address2": "Suite 430",
"city": "Austin",
"country": "US",
"email": "[email protected]",
"fax": "123-867-5309",
"first_name": "John",
"id": "ea95132c15732412d22c1476fa83f27a",
"last_name": "Appleseed",
"organization": "Cloudflare, Inc.",
"phone": "+1 123-123-1234",
"state": "TX",
"zip": "12345"
},
"registry_statuses": "ok,serverTransferProhibited",
"supported_tld": true,
"transfer_in": {
"accept_foa": "needed",
"approve_transfer": "unknown",
"can_cancel_transfer": true,
"disable_privacy": null,
"enter_auth_code": "needed",
"unlock_domain": null
},
"updated_at": "2018-08-28T17:26:26Z"
}
],
"success": true,
"result_info": {
"count": 1,
"page": 1,
"per_page": 20,
"total_count": 2000
}
}
if you wanted to use https://developers.cloudflare.com/api/operations/registrar-domains-get-domain to get a domain, you wont find {domain_name} by listing the domains as mentioned above. this probably could have been avoided if instead this endpoint required the {domain_id}, which actually IS included in each objects results from the above.Cloudflare API Documentation
Interact with Cloudflare's products and services via the Cloudflare API
Cloudflare API Documentation
Interact with Cloudflare's products and services via the Cloudflare API
for individual endpoints, you're best to file a support ticket or submit feedback using the link on the API docs page for it to be routed to the correct team.
https://developers.cloudflare.com/fundamentals/setup/find-account-and-zone-ids/ will help you find the correct identifier for your requests in case you are still having issues finding the right ones.
Find zone and account IDs · Cloudflare Fundamentals docs
Once you set up a new account and add your domain to Cloudflare, you may need access to your zone and account IDs for API operations.
its not that i cant find them.. its that i have to find them in the first place... i was trying to avoid having to code my script manually for each and every endpoint. "if" things were consistent, and used the name of the actual value needed for the url query, i could use a little bit of simple logic to programmatically walk the entire api to get all the data. but this is not the case. since {identifier} doesnt actually provide useful information, i am forced to manually write the functions for each and every endpoint, having to reference the api docs to know what value ill need for further requests.
the 'Web Analytics' endpoint is one perfect example.
https://api.cloudflare.com/client/v4/accounts/{account_identifier}/rum/site_info/{site_identifier}
i can not look at that endpoint url and work out what the actual name of the values are that i need to populate in the url without having to look it up in the docs.
if i get the list of accounts by getting the following endpoint, there is no value in the returned objects thats named "account_identifier"
https://api.cloudflare.com/client/v4/accounts/
and in this example the 'site_identifier' that i need... the value is actually named 'site_tag'
but theres no way for me to know that just by looking at the url
where as if the url was /accounts/{account_id}/rum/site_info/{site_tag}, i would know i need to get the 'id' value from /accounts, and the 'site_tag' value from /accounts/{account_id}/rum/site_info/list
so instead of referring to the value as identifier, requiring one to figure out what that means, just go ahead and identify it by useing the value name instead...
its a difference of having to manually write code to handle each endpoint individually vs be able to programmatically walk the api using the information thats in the url alone as a means to knowing what values are needed.
so im approaching almost 2000 lines now :/ and im about 3/4 of the way though all the endpoints...cc @rickyrobinett, this is some great feedback for the future
i think it would also be handy if the api reference doc indicated what minimum level of account (free, paid, pro, etc) youd need to access each endpoint is =]