Hacker News Reader

Comment by jasonhansel | Hacker News Reader

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.

View on HN

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.

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.

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.

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

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

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!

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.

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.

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.

FWIW you can add HTTP Basic Auth information in URL links and all major browsers and other HTTP clients (for the most part) should interpret it correctly.

https://:[API_KEY]@v6.exchangerate-api.com/v6/latest/USD

If you only have an API key and not a token (username) and secret (password) I recommend passing the API key as a password as some logging solutions do log the basic auth username in the data recorded.

How does that work for authenticated requests?

The same way you would build any login system for a browser application.

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

> is it for security

Yes.

EDIT: specifically, it is do intercepting a request doesn’t allow you to issue new requests.

Isn't that what https provides. Or were the APIs creates before https was popular

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

> is it for security

It is because TLS client certificates do not exist.

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.

Looking at you literally all of AWS.

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.

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)

Reply on news.ycombinator.com