Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

What’s your API’s “Time To 200”?

shkspr.mobi

Post reply on HN
Print view View original

41–50 of 90 posts

Re: What’s your API’s “Time To 200”?

#41

Post by dmlittle »

256DEV wrote: post #36
treve wrote: post #28

Earlier quoted context omitted.

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 funct…

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.

Re: What’s your API’s “Time To 200”?

#42

Post by justin_oaks »

dylan604 wrote: post #34
justin_oaks wrote: post #19

While "Time to 200" is an important metric, it's also important to have complete enough documentation for people to effectively use the API. There shouldn't be wholly undocumented corner cases. For example, I was using the Docker Engine API and I was trying to use the container GET archive call. The documentation says to use a file path, but it doesn't indicate the behavioral difference between using a file path endi…

>only covers happy paths or frequent uses, Maybe, but there's no way a dev can possibly think of every single crazy thing an end user will try to do. There's a reason things are referred to as edge cases. You design a system to to work a specific way, and then document the workflow to make it work. Anything outside the documented procedure is eperimental. Sure, a dev can build as many bozo tests into the thing that t…

Valid point. Perhaps use of "corner cases" didn't help my point. I mean that there shouldn't be valid, intended functionality that remains undocumented.

Another example is an API I use that has a property that has no documentation other than the property's presence. I just roll my eyes at that.

Re: What’s your API’s “Time To 200”?

#43

Post by gowld »

1123581321 wrote: post #18
dinkleberg wrote: post #2

It always boggles my mind when I try to use a new API and I have to jump through a hundred hurdles to start using it. Let me use your service and start paying you! In the ocean of bad APIs out there I'll pick yours if you can offer: 1. An easy process to onboard 2. Good documentation 3. Usage based pricing

Agreed with the first two. I’m happy with a different pricing model so long as it’s financially viable at our usage tier and self-serve. On a project with a budget, or with funding, there isn’t a meaningful difference between a free trial, prorated per call, and paying for a month upfront.

Those are all "usage" based if you aren't nitpicking. The major alternative is app store (and some SDKs) style of revenue-bases pricing

Re: What’s your API’s “Time To 200”?

#44

Post by gowld »

dylan604 wrote: post #34
justin_oaks wrote: post #19

While "Time to 200" is an important metric, it's also important to have complete enough documentation for people to effectively use the API. There shouldn't be wholly undocumented corner cases. For example, I was using the Docker Engine API and I was trying to use the container GET archive call. The documentation says to use a file path, but it doesn't indicate the behavioral difference between using a file path endi…

>only covers happy paths or frequent uses, Maybe, but there's no way a dev can possibly think of every single crazy thing an end user will try to do. There's a reason things are referred to as edge cases. You design a system to to work a specific way, and then document the workflow to make it work. Anything outside the documented procedure is eperimental. Sure, a dev can build as many bozo tests into the thing that t…

If your API has unpredictable corner cases, your data model or API is wrong

Re: What’s your API’s “Time To 200”?

#45

Post by [deleted] »

thecodemonkey wrote: post #29
edent wrote: post #22

Earlier quoted context omitted.

The demo link is a good start - but it would be nice to have the JSON output pretty-printed. I'm not sure that the first thing I should see in the documentation is the changelog. But, other than that, I like it. If you offered UK/EU geocoding, I'd use it :-)

Thanks so much for the feedback! I've considered checking the User Agent and rendering pretty-printed JSON if e.g. a webbrowser is used, but I am a bit worried that UA-dependent behavior could be confusing. Perhaps the downside to always rendering pretty-printed JSON is minimal? Would love some thoughts on this. Good call on the changelog being front and center, moving it a bit further down now. Thanks! UK/EU geocodi…

[deleted]

Re: What’s your API’s “Time To 200”?

#46

Post by dheera »

robalfonso wrote: post #23
jasonhansel wrote: post #20

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.

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.

Re: What’s your API’s “Time To 200”?

#47

Post by resonantjacket5 »

Kiro wrote: post #39
256DEV wrote: post #25

I've put a fair amount of work into getting this exact time as low as possible for my exchange rates API [1]. I've noticed slightly better conversion each time I've taken a major step out of the process. I've specifically eliminated some of the steps this article cites in its example of a tedious flow - for instance I changed user accounts to be confirmed by default and then only disable them retroactively if a user…

> I'm not sure how I could further improve the current flow Remove 1 and 2.

You need to assign the API key to an email both for contacting and also a way to limit abuse.

Re: What’s your API’s “Time To 200”?

#48

Post by marcosdumay »

aszen wrote: post #26
jasonhansel wrote: post #20

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.

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

It is because TLS client certificates do not exist.

Re: What’s your API’s “Time To 200”?

#50

Post by KeepFlying »

resonantjacket5 wrote: post #47
Kiro wrote: post #39

Earlier quoted context omitted.

> I'm not sure how I could further improve the current flow Remove 1 and 2.

You need to assign the API key to an email both for contacting and also a way to limit abuse.

But you could give a short lived highly limited API key out for testing to allow the potential user to test the API for their needs before bothering to make an account and providing their personal information.
Post reply on HN