What’s your API’s “Time To 200”?
shkspr.mobi
shkspr.mobi
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 doesn't click the activation link within 24 hours. This way you don't need to wait for the confirmation email. Even though I use Postmark delivery times can be surprisingly variable.
I'm not sure how I could further improve the current flow, which is 1. put your email into the landing page, 2. then choose a password for your account, then 3. you're presented with an example request format including your already activated API key. Suggestions welcome!
I guess because the scope of my service is so limited it's easy to have this fast flow, no complex libraries or auth is involved.
Remove 1 and 2.
Basically hand out tons of short lived credentials right from a widget on the main landing page, together with each API response giving a link to a signup form that can convert the key into a fully fledged account.
Thanks for the suggestion!
With my experience though I found that trying to limit signups to prevent abuse caused so much friction for legitimate users that I actually decide to change my strategy to the following:
1. Allow essentially unrestricted access to the free account on a separate domain/hosting so that people don't feel the need to churn through accounts with bots etc. and the load can be separated out. Hence this page: https://www.exchangerate-api.com/docs/free My signup form actually automatically redirects some classes of disposable email, bot signup etc. to this page!
2. Make sure that anything particularly resource intensive or that's a good reason to sign up for my service is only accessible after payment. I would love to give out more functionality for free but unfortunately the people that take advantage mean it's just not economically possible.
So for me the main reason to get an email address is 1.) so that users can have a better experience - get usage notifications, updates about the API that might affect them, share the account with a colleague etc.
And 2.) so that business users can be satisfied. Pretty much anyone running a company that is relying on an API will want to have an account, see how the upgrade process would work if they needed it etc. even if they're only starting off with a free plan.
You can see it here: https://www.exchangerate-api.com/docs/free
That said, as much as some users want an open endpoint with zero authentication there are many others who want an actual account, commercial support, high availability, more features etc. These users are also the ones that pay for development, infrastructure etc. so my service has to be 95% built around the flow that includes signup.
If you’re just interested in putting together a quick hack or proof of concept, the private API often has a “time to 200” orders of magnitude faster than the public developer API: pop open the Network tab on your browser, perform an action, copy as cURL, run in terminal. Boom, 200. Twiddle a few parameters so it does what you want, and get on with building your demo or hack.
If that kind of learn-by-example speed was available for the developer API - or, better yet, companies actually used the same API for their service as a form of both dogfooding and to provide a great example, the API world would be a happier place.
- 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.
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.
such a pain to debug, i'm not sure why they have such signing features. is it for security
Yes.
EDIT: specifically, it is do intercepting a request doesn’t allow you to issue new requests.
For example, S3. S3’s authentication scheme allow you create a limited used download link and passing to a untrusted user
It is because TLS client certificates do not exist.
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!
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.
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.
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.
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
But then it works just fine! :P
4. A meaningful indication of API stability and planned longevity
5. A viable method to run automatic integration testing during development
I want an honest answer to how often you're expecting to break my integration and cause me extra work, and if you do that, I want to be confident that I've done enough to update my integration so it still works without having to manually retest the entire thing.
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 ending in "/" and one ending in "/."
I had to look at the "docker cp" documentation to figure that out.
If your documentation makes it difficult to complete a project because it only covers happy paths or frequent uses, then your users are going to have a rough time.
Both the "Time to 200" and "Time to real project usage" indicate how important usability testing and documentation is.
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 they can think of, but users will always come up with something different.
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.
I've had to require email verification, non-cloud IP signup, block signup from IPs of already blocked users, in order to combat abuse. In all of these cases the user is just prompted to add a card to continue using.
I wish it weren't this way though, as it does harm the user's experience...
You can see him talking about time to triangle on various Playstation consoles here [2] (and if you have the time, it's definitely worth watching the entire talk).
[1] https://www.engadget.com/2013-06-28-cerny-ps4s-time-to-trian...
For instance if there is 2 or 3 alternative services, and you want to explore one of them to have a better idea of the trade-offs. Setting up an account and making “real” requests will be your benchmark.
Actually, even for a service with a decent chance to commit to it, there will still be an exploration phase to get an estimate for the implementation cost. Depending on how much the devs struggle to just try the API, the project could get more or less reprioritized for lower hanging fruits.
It is acceptable to not provide support unless you pay, and to allow more requests in a time period if you sign up. (This seems to be the case for the exchange rate API mentioned in another comment, so that is OK.)
https://news.ycombinator.com/item?id=22940781
I said its surprising how much breath the sales engineer is wasting given how coveted a continual flow of oxygen is now. I was being facetious in April 2020 but who knew how insensitive that would become!
We generalised it over time to “time to value” for anything that isn’t onboarding/data-fetching
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 :-)
Good call on the changelog being front and center, moving it a bit further down now.
Thanks! UK/EU geocoding may or may not happen in the future :)
I really can't think of any other suggestions - your landing page is excellent, fast and I imagine highly converting with all the social proof. I also like the specific landing pages for each customer segment a lot, I really need to do that for my service.
Your site inspires me to work more on mine!
Something that would consolidate account, tokens, billing, tracking, firewalling etc of an API?
Somewhere where one could plug their api and monetize it easily?
I imagine all the cloud platforms have similar products
That feeling of not being sure if a tool/API/service/SDK/library/hardware is going to work for your purposes and then you get that first example/test/demo running and get your first response...
"Ok, yep, this is good! Now is it gonna let me change this small thing so I can..."
And the positive feedback loop has begun!
It's definitely a metric that impacts developer adoption & is IMO something that needs to be routinely tracked in order to reduce the time taken to get started & catch any unexpected regressions.
* Zero is not a HTTP return code
* You don't want to get all the returen codes up to 200, as you'd get with speed. You want HTTP 200 OK and nothing else.