设计公共API的六个注意事项

http://sd.csdn.net/a/20120814/2808557.html


 
API by thesmith
俗话说：“好东西就要贡献出来和大家一起分享”，尤其是在互联网业务高度发达的今天，如果你的创业公司提供了一项很酷的技术或者服务，并且其他用户也非常喜欢该产品，在这种情况下，最好的解决方案是什么呢？把它作为一项服务——通过RESTful API的形式进行开放共享。

嗨，别忘了，如果这样做，未来它或许会像Twitter那么有名。当然它可能也会给你带来些荣誉，或者会给你带来不菲的收入，好了，下面让我们来谈谈如何做一个API呢？

提供一个基于内部架构之上的相同接口，打开它，最后在诸如HackerNews、Twitter、和Reddit 这类的技术论坛上宣布一下，这样就好了吗？就这么简单吗？

答案当然是否定的，如果要提供一个优质的公共API接口，你至少需要做到以下六点：

授权开发人员的规则
注意限流控制
确定是否要收费
通常，如果收费，那么请求越多，钱就越多——你需要准备一个计价表
利用好工具对服务端进行监控
好的技术和帮助文档
支持
支持
支持
..........

以上提到的，都是你必须要提供的。

注意事项

在权限分配方面，你需要根据客户来提供相应的API接口。或许有些API需要采取不同的配额，或许限流的多少，这些都需要取决于所需资源和服务请求数。

仔细思考一下，这远比讨价还价来的更划算一些——只需提供一个API在外面，如果该API比较受欢迎，它还会给你的创业带来些额外的收入。

几年前，我曾开放一个自己做的API，仅仅是一个REST调用，我自己都无法保证它是否真正能够使用，当然最后结果的确是这样，而且问题很多。

许多人在我毫不知情的情况下使用该API，更不用说监控了。直到有一天，我突然发现服务器开始不稳定并且无论我怎么调整都没有恢复，最后关闭所有应用程序，可是服务器仍然没有恢复正常。

于是我想起了那个开放的API，我发现它在HackerNews、 Reddit和Twitter上都受到了不同的关注。当我关闭这个API入口并且服务器恢复正常的时候，我竟然收到邮件：“Hey，到底怎么了？我一直在使用那个API，你怎敢把它给关了呢？”

什么，你都没有告诉我在使用它，没礼貌的家伙！

当然，这并不是他们的错，虽然我留有开发账号，限流，使用配额诸如此类的信息在上面，但是开发人员更多是看到一个很酷的API，便开始使用它。

如何恰当的提供一个API？



Auth, by oztenphoto
正如上面提到的，需要准备许多东西，如果希望成为你和用户之间非常愉快的体验，尤其是对用户来说。其中一个方法是自己动手构建所有的基础设施——但这需要大量的时间而这并不是很性感的做法。专注于产品核心问题比确保其他的工作更重要。

幸运的是，目前已经有一些服务可以让API使用起来更简单更方便。

据我所知道有3scale，Mashape和Mashery。

基本上所有的这些服务都需要提供诸如：开发者密钥，一个主文档，执行速度限制、确保分配正确以及一系列分析工具等等。你需要提供一个像样的API服务不仅要让开发人员满意，还要让你的服务器也满意才行。

API的主要差异在与如何实现？当3scale在服务器端不停的问：“嗨，这个用户做的怎样？可以吗？好吗？”的时候，Mashape和Mashery仅提供一种代理工作机制，对用户进行保持跟踪并且只有在适当的时候才会发送请求。

这意味着你必须提供一些Mashape可以理解的标准，但很酷的是，他们会在客户端根据相应地平台自动创建一些库，并且他们是唯一的提供商，这样就可以采取收费措施，所以这样也就迎合了他们自己的想法，是不是很帅！

接下来，做一款炫的产品，提供API，并且让它得到关注吧。

英文原文：So you want to offer a public API …
http://www.zemanta.com/fruitblog/so-you-want-to-offer-a-public-api/ uly 25, 2012 by
Swizec Teller |
7 Comments




API, by thesmith

You are awesome.

Your startup just came up with a cool new piece of tech. Others might want to use it as well. The best way to do that is offering it up as a service – a RESTful API even.

Hey, it made
Twitter famous. Surely it will help you gain some traction as well … Might even make you some money! Now we’re talking!

So … what goes into making an API?

You just take the same interface your
over-architected architecture uses internally, open it up, announce it on
HackerNews and Twitter and
Reddit and away we go. Right? Right.

Not right.

To offer a public API you need:

some way to authorize developers
throttling control so you don’t get swarmed
deciding whether you’re going to charge money or not
usually when charging, more requests means more money -> you need a way of enforcing quotas
good
tools to see what’s happening with the service
good documentation
support
support
support
Did I mention you are going to have to offer support?

Effort

Oh and don’t forget permissions, maybe you want to give different people access to different endpoints of the API. Maybe some parts of the API have different usage quotas than others, or perhaps the throttling behaves differently depending on how many resources
it takes to service different requests.

Suddenly, this is much more than you bargained for – all you wanted is to simply throw an API out there, see if it sticks and maybe collect some side income for your startup.

I know, I’ve been there.

A few years ago I offered an API without making sure I’m doing it properly – it’s just a single REST call, what could possibly go wrong? As it turns out, plenty.

A bunch of people started using the API and I had no way of measuring or knowing that. All
I could see was that the servers suddenly started melting and that no matter what I did they wouldn’t bloody stop. Turned off everything and the servers were still melting.

Then I remembered that throw-away API offering that got a bit of traction on HackerNews and a tiny bit on Reddit and quite a bit on Twitter. Shut down access to that, stopped the servers from melting and suddenly started receiving emails from disgruntled
developers “Hey, I was relying on that API! WTF happened!? How dare you take it off?”

Screw you, you didn’t even have the courtesy of telling me that you’re using it.

No fault of their own of course, I was the one who’s supposed to have developer accounts, throttling, usage quotas and whatnot. The developers just saw a cool API and started using it.

How to properly offer an API

Auth, by oztenphoto

As mentioned before, you are going to need a lot of … stuff, if you’re going to make this a pleasurable experience both for you and your users.

Especially your users.

One way is to build all of the infrastructure yourself – but that takes a lot of time and isn’t very sexy at all. Much better to worry about the core problems of your product than making sure some side thing works robustly.

Lucky for you (and your users) there exist a bunch of services whose purpose is making APIs fairly easy and palatable.

The ones I know of are
3scale,
Mashape and
Mashery.

Essentially all of these services provide stuff like developer keys, a place to host documentation, enforcing rate limits, making sure the right quotas are assigned to the right person, giving you great analytics tools and so on. Basically everything you
need to provide a decent API service that keeps developers and your servers happy.

Major differences lie mostly in implementations. While 3scale is something you use server-side and keep asking “Hey, can this user do that? Can they? Right now? Okay!”, Mashape and Mashery work as a sort of proxy where they keep track of everything
on their own end and only send requests your way when appropriate.

Of course this means you have to conform to some sort of standard that Mashape can understand, but a really cool consequence is that they automatically create client libraries for all sorts of different platforms. And they’re the only provider that lets
you start charging money right away (by doing it instead of you), so maybe conforming to their ideas of API isn’t that bad at all.

I haven’t personally used these services before, but I have not-used them … it’s not good.

The next time you offer an API let somebody else take care of it, so you can go back to Making Cool Things ™ instead of answering the
“You offer 1000 requests for free, but I need 1013 and don’t want to pay” email for the umpteenth time.