6 ms·

Personally, few things annoy me more than APIs that can only be accessed via an SDK, and can't easily be called through e.g. cURL.

robalfonso 5y ago
I seriously discount your api if I can't do my initial review via curl. As the author stated, having to do all this setup creates friction, your api is supposed to be solving a problem for me. If it just creates different problems you're not offering a good solution. If I can quickly see how it works via curl it will be that much easier to evaluate.
- dheera 5y ago
  Also please have an example API key that actually works. There are some ways to do this depending on your use case - Have a rotating example key in your docs that rotates once a week. - Have the example API key return redacted data, example data, or old data instead of real data instead of failing out as an invalid key. - Add something to the response that doesn't make it usable in production (e.g. a TTS API response can have some duck noises in the background for the example key) - Limit the total number of requests per IP address to something that's usable for dev work but not usable in production It reduces a LOT of friction for the user to be able to just curl something off your website instead of going through the whole registration process to get the first 200.
  - robalfonso 5y ago
    Agreed, extra credit when the docs use the key from your account so that you can just grab strait from the docs, I think it's stripe who I'm thinking of who does that, sooooo nice.
Spivak 5y ago
Looking at you literally all of AWS.
- deleted 5y ago
  [deleted]
- seanp2k2 5y ago
  To be fair, it’s not like the GCP APIs are much easier to use. It’s probably the right thing for infra and payment services to have a higher bar for API security, plus they’re hugely complex and usually used as an SDK. That said, I haven’t been very impressed with the Google API dev experience. Example: I was just trying to post some timing data to Google Analytics via Go, and the documented example didn’t work in addition to being very hard to find. I eventually got lost in Firebase docs, which appeared to be wholly unrelated to what I was trying to do, had many additional separate APIs, required that I set up a new project in Firebase in addition to my GA “property”… On top of all of this, the GitHub auto-generated API examples were outdated (used a previous version that referenced deprecated docs) with no hints as to where to go from there. In the end, I gave up, because I wasn’t willing to invest hours into learning all the idiosyncrasies. Ended up using Influxdata’s SaaS and got what I wanted going in about 15 minutes. To be fair, most of that time was also because their API docs didn’t actually work as posted and didn’t go through properly installing the client lib, which someone more experienced with Go probably would have gotten past more quickly.
  - vishwajeetv 5y ago
    If you are trying to pass custom json to GA, simply you can't do that. You would have to use Firebase analytics to send custom JSON. For GA, all the data that is passed must fall under these types, categories, actions, labels (and value)
aszen 5y ago
famous example of this, are most of the aws api's that because of their signing features and hashes can really only be called sanely from an sdk. such a pain to debug, i'm not sure why they have such signing features. is it for security
- dragonwriter 5y ago
  > is it for security Yes. EDIT: specifically, it is do intercepting a request doesn’t allow you to issue new requests.
  - aszen 5y ago
    Isn't that what https provides. Or were the APIs creates before https was popular
    - j16sdiz 5y ago
      The use case is different. For example, S3. S3’s authentication scheme allow you create a limited used download link and passing to a untrusted user
- marcosdumay 5y ago
  > is it for security It is because TLS client certificates do not exist.
- nexuist 5y ago
  I would say it is fair for AWS to have a complicated signing method, because you really do not want your AWS account falling into the wrong hands or being intercepted through some MITM attack. With an AWS account an attacker can bankrupt you pretty much instantly.
treve 5y ago
Or even better: allow me to paste the url in a browser and get a meaningful result.
- 256DEV 5y ago
  My API currently does auth inline in the GET request URL in order to make this possible. An example request would be: GET https://v6.exchangerate-api.com/v6/YOUR-API-KEY/latest/USD https://v6.exchangerate-api.com/v6/YOUR-API-KEY/latest/USD I've had a fair number of users send me feedback saying this isn't the best practice, I should use tokens in HTTP auth headers or use various other auth schemes. But from my perspective, for an API that is offering really very simple functionality, using HTTPS & not handling user data etc. then this is quite OK - especially when you consider the benefits of how simple it is to get up and running. I have quite a few university course conveners include my free API in their entry level CS classes because it's super fast & rewarding for students to go from finding my API to then having a JSON object in their code, no tokens required!
  - dmlittle 5y ago
    The problem with having your API key in the URL is that they'll likely be logged all over the place when they're meant to be secret. You probably have the keys being leaked in logs, error reports, metrics, etc.
    - KeepFlying 5y ago
      True and if this API handled user data or anything substantially private that would be a HUGE deal and super dangerous. But it seems like in this case it's mostly a rate limiting and identification exercise and not a secure protection of user data so the impact of exposure is substantially lower. So it does seem reasonable here. Though I hope that OP has documented all over the place "do as I say not as I do" so people don't copy this pattern.
      - 256DEV 5y ago
        dmlittle's concern is a valid one and for most other types of API I would definitely agree it's not the right approach. I still think it's reasonable for my use case but perhaps I should add another auth scheme as an optional alternative for the user who is concerned about their key potentially being caught in logs. Your point about the documentation is also a good one - I should probably add a specific page just about the authentication approach. Added to the to-do list! Thanks.

robalfonso 5y ago

I seriously discount your api if I can't do my initial review via curl. As the author stated, having to do all this setup creates friction, your api is supposed to be solving a problem for me. If it just creates different problems you're not offering a good solution. If I can quickly see how it works via curl it will be that much easier to evaluate.

dheera 5y ago
Also please have an example API key that actually works. There are some ways to do this depending on your use case - Have a rotating example key in your docs that rotates once a week. - Have the example API key return redacted data, example data, or old data instead of real data instead of failing out as an invalid key. - Add something to the response that doesn't make it usable in production (e.g. a TTS API response can have some duck noises in the background for the example key) - Limit the total number of requests per IP address to something that's usable for dev work but not usable in production It reduces a LOT of friction for the user to be able to just curl something off your website instead of going through the whole registration process to get the first 200.
- robalfonso 5y ago
  Agreed, extra credit when the docs use the key from your account so that you can just grab strait from the docs, I think it's stripe who I'm thinking of who does that, sooooo nice.

Spivak 5y ago

Looking at you literally all of AWS.

deleted 5y ago
[deleted]
seanp2k2 5y ago
To be fair, it’s not like the GCP APIs are much easier to use. It’s probably the right thing for infra and payment services to have a higher bar for API security, plus they’re hugely complex and usually used as an SDK. That said, I haven’t been very impressed with the Google API dev experience. Example: I was just trying to post some timing data to Google Analytics via Go, and the documented example didn’t work in addition to being very hard to find. I eventually got lost in Firebase docs, which appeared to be wholly unrelated to what I was trying to do, had many additional separate APIs, required that I set up a new project in Firebase in addition to my GA “property”… On top of all of this, the GitHub auto-generated API examples were outdated (used a previous version that referenced deprecated docs) with no hints as to where to go from there. In the end, I gave up, because I wasn’t willing to invest hours into learning all the idiosyncrasies. Ended up using Influxdata’s SaaS and got what I wanted going in about 15 minutes. To be fair, most of that time was also because their API docs didn’t actually work as posted and didn’t go through properly installing the client lib, which someone more experienced with Go probably would have gotten past more quickly.
- vishwajeetv 5y ago
  If you are trying to pass custom json to GA, simply you can't do that. You would have to use Firebase analytics to send custom JSON. For GA, all the data that is passed must fall under these types, categories, actions, labels (and value)

aszen 5y ago

famous example of this, are most of the aws api's that because of their signing features and hashes can really only be called sanely from an sdk. such a pain to debug, i'm not sure why they have such signing features. is it for security

dragonwriter 5y ago
> is it for security Yes. EDIT: specifically, it is do intercepting a request doesn’t allow you to issue new requests.
- aszen 5y ago
  Isn't that what https provides. Or were the APIs creates before https was popular
  - j16sdiz 5y ago
    The use case is different. For example, S3. S3’s authentication scheme allow you create a limited used download link and passing to a untrusted user
marcosdumay 5y ago
> is it for security It is because TLS client certificates do not exist.
nexuist 5y ago
I would say it is fair for AWS to have a complicated signing method, because you really do not want your AWS account falling into the wrong hands or being intercepted through some MITM attack. With an AWS account an attacker can bankrupt you pretty much instantly.

treve 5y ago

Or even better: allow me to paste the url in a browser and get a meaningful result.

256DEV 5y ago
My API currently does auth inline in the GET request URL in order to make this possible. An example request would be: GET https://v6.exchangerate-api.com/v6/YOUR-API-KEY/latest/USD https://v6.exchangerate-api.com/v6/YOUR-API-KEY/latest/USD I've had a fair number of users send me feedback saying this isn't the best practice, I should use tokens in HTTP auth headers or use various other auth schemes. But from my perspective, for an API that is offering really very simple functionality, using HTTPS & not handling user data etc. then this is quite OK - especially when you consider the benefits of how simple it is to get up and running. I have quite a few university course conveners include my free API in their entry level CS classes because it's super fast & rewarding for students to go from finding my API to then having a JSON object in their code, no tokens required!
- dmlittle 5y ago
  The problem with having your API key in the URL is that they'll likely be logged all over the place when they're meant to be secret. You probably have the keys being leaked in logs, error reports, metrics, etc.
  - KeepFlying 5y ago
    True and if this API handled user data or anything substantially private that would be a HUGE deal and super dangerous. But it seems like in this case it's mostly a rate limiting and identification exercise and not a secure protection of user data so the impact of exposure is substantially lower. So it does seem reasonable here. Though I hope that OP has documented all over the place "do as I say not as I do" so people don't copy this pattern.
    - 256DEV 5y ago
      dmlittle's concern is a valid one and for most other types of API I would definitely agree it's not the right approach. I still think it's reasonable for my use case but perhaps I should add another auth scheme as an optional alternative for the user who is concerned about their key potentially being caught in logs. Your point about the documentation is also a good one - I should probably add a specific page just about the authentication approach. Added to the to-do list! Thanks.