cloudflare/python-cloudflare

Docs: Provide information on how arguments are mapped to API paths

M1kep opened this issue · 6 comments

M1kep commented

With the lack of type hints/ability to goto definition, it would be nice to have a section in the README about how API paths are mapped to arguments. I was thinking it'd fit in well with the Cloudflare API version 4 section where the following statement is:

Each API call is provided via a similarly named function within the CloudFlare class

I think expanding on this to explain how path arguments, ideally multi-part paths, are provided to the functions.
ie. https://api.cloudflare.com/client/v4/accounts/{account_id}/members/{member_id}

While I'm sure there's an instance of this in one of the many examples, having a small section near/in the Cloudflare API version 4 portion would make translating from API docs to SDK calls much easier to quickly understand.

mahtin commented

I think I understand the question; however, have you looked at the examples folder?

I'll think about issue further before the next release.

mahtin commented

Would you be looking for something like this:

The following API call:

    https://api.cloudflare.com/client/v4/accounts/{account_id}/members/{member_id}

Translates to:

    results = cf.accounts.members(account_id, member_id)

Would that help?

  • 👍1
allwalte commented

Not the OP, but as someone who was trying this for the first time today I think the above would be very helpful. I did figure it out, it's obviously not super difficult, but the explanation above would have saved a bit of time anyway.

mahtin commented

OK. I'll add something near the top of the README file.

securitypedant commented

I agree, it took me a little while to figure out how the API calls are mapped to SDK calls.

mahtin commented

In version 2.19.4 the README file has been updated with a better explanation addressing this.