Almost everyone is doing the API economy wrong | Hacker News Reader

Almost everyone is doing the API economy wrong

techcrunch.com

114 pointsjstoiko40 comments

I've seen a lot of APIs on ReadMe.io, and one thing I've noticed is that many APIs tend to be built as though replicating the main site is the only usecase. Before launching an API, you should come up with 5-10 compelling usecases that someone couldn't use your website for.

You should publicly post these usecases somewhere, too, as a type of "Request for Projects". It gives people ideas... after all, you spend more time thinking about your API than anyone else ever will.

> "Before launching an API, you should come up with 5-10 compelling usecases that someone couldn't use your website for."

Not necessarily. Sometimes what you want is to combine data from multiple sources in interesting ways. A single API doesn't need to be versatile, it just needs to make useful information available.

Sure, this counts as a compelling usecase. Maybe your API just lets users list Items chronologically since that makes sense for your site, but someone else wants to get Items by location.

Many times, the only way to do what you want with data is to use the API to get everything, then transform it locally. This is obviously really inefficient (and sometimes impossible).

This is true, but if you never take the effort, I'd expect you to build a pretty bad API.

The vain of my existence. APIs are about data structures, relationships and metadata. Give me these things without requiring me to go through your GUI to figure out what goes where. And yes, do come up with use cases for the API. Try and see it from the point of view of someone who does not know the implementation details. It's a very simple concept that for some reason gets lost.

Bane, not vain

I typed vain, vein and vane, but not bane. :)

HAL - Hypertext Application Language

"HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API. Adopting HAL will make your API explorable, and its documentation easily discoverable from within the API itself. In short, it will make your API easier to work with and therefore more attractive to client developers. APIs that adopt HAL can be easily served and consumed using open source libraries available for most major programming languages. It's also simple enough that you can just deal with it as you would any other JSON."

http://stateless.co/hal_specification.html

Yes, pretty much HAL. I've never seen an API use this in the real world. I integrate with a lot of non-startup APIs and they can barely respond with proper JSON.

I agree, Greg! Started a newsletter earlier this year to interview API companies and share those killer usecases: https://tinyletter.com/getputpost

> Before launching an API, you should come up with 5-10 compelling usecases that someone couldn't use your website for.

Disagree. The most important thing by far is to have an API at all. Just being able to build your main site but with a different UI (or as a native program) is a more than good enough use case to make it worth publishing an API.

By all means improve the API if you can, but having one at all is the most important thing. And as people start using it they'll naturally map out the use case space and you can see what cases come up - rather than trying to figure out which interfaces people will need up front, it's much more efficient to respond to feature requests as they arise.

I agree that you want to do some thinking before launching an external API. A nice intermediate low risk step would be to launch the API internally and see how useful it is for folks in the organization. I did that a few years ago and it turned out to be very useful.

Plus it gives you a safe space to learn about the intricacies of running an API before you charge for it.

Also, as a developer if I heard "we are exposing an internal API and charging for it" I'd be confident that the API would be around.

"If you build it, they will come." Except they won't.

It seems to me that, unless your product is a platform, you probably shouldn't publish a public API until someone requests it as a feature. And you should charge for it, especially if your hosting the API endpoint. Turn it into direct revenue to support the development and maintence of those API features.

If we're talking here only about web APIs where there is an economy (meaning that money changes hands), then I don't think that it's fair to say that most are doing it wrong. This is relatively new territory and it is taking time to flesh out the business models. Look, newspapers are still trying to figure out the business models.

Information consumed by eyeballs has different business models. You can paywall or you can have it ad-supported (or both). API clients don't have eyeballs, so ad-supported isn't an option. Microsoft has the Azure Data Marketplace, which is the only monetized API market that I'm aware of. My company provides APIs for cloud ETL that companies pay an annual subscription to use. You could say that Amazon Lambda is a metered API. My own opinion is that there will be lots of different business models. This is just getting started.

You guys know you really mean "Web API" and not "API", right?

This kind of phraseology is a clear sign that someone's programming experience is extremely narrow in scope.

It's just an abbreviation. They use the full "web API" in the sixth paragraph.

sarcasm?

I know what you mean. Coming from a C background, I had the hardest time adjusting in the last few years to what "web" guys mean when they say "API".. but, language evolves, and I've come to accept it. If you can't beat 'em, join 'em.

It also depends on the context. Typing Web API everytime is stupid. We say Linux, not GNU/Linux or Chrome instead of Google Chrome.

What's the context here though?

I had to skim like 5 paragraphs to even know wtf the title meant.

The context is that it's a TechCrunch article, and I imagine much of TechCrunch's audience are not programmers and don't understand the distinction.

In case you are asking genuinely, the "API economy" buzzword was coined a few years ago to describe business models based or largely reliant on web APIs.

To how many products does this article apply? Only super huge platform products, like Facebook, Instagram, Twitter, Dropbox and Uber, right? Perhaps 2 or 3 high-business services. Google services have super limited APIs, Airbnb has none, WhatsApp has none. All other APIs are unmonetizable.

I work on a product that uses several third party, paid APIs.

- postcode lookups

- sending email

- sending SMS

- multi-hop route planning

- engineer appointment scheduling

This is not the kind of API the article is about. These are paid services that happen to be accessible through APIs, not API ecosystems.

I want to do it right, so I want to ask you:

Question 1: Is there a de facto API/service description language standard out there?

Optional question 2: Which would be the best choice for a decentralised internet of services?

Answer 1: Swagger is the de facto. It seems to have low actual usage, but high midshare. As time goes on, I expect there to be a much higher usage of Swagger, since pretty much all API services accept it.

(Other options include RAML, Blueprint and IO Docs, but Swagger has the momentum)

Thanks! I figured the same. OpenAPI seems to be it.

WSDL on the other hand seems to be dead and/or unusable. Even one of its creators described it as a "train wreck" :)

Oh gods yah. WSDL should die painfully in a fire with all the people in its standards committee

The basic WSDL stuff is OK. It's the WS-n extensions that are truly the Zed of this world.

>WSDL on the other hand seems to be dead

Yeah, it's not. It's still what people in big enterprises do, or what people who want to do a quick API use.

If you're a .NET developer it's pretty easy to consume WDSL/SOAP services, so you might be more inclined to just use it when creating your own webservices.

There's of cause also the group that doesn't really know what they're doing, who just slaps a webservice method decorator on whatever internal function they wish to expose. Those are usually the worst APIs.

But yes, WDSL is a train wreck.

The c# version is swashbuckle... And I agree swagger is awesome... As long as the monkeys that consume your service will actually look at it

We use Swagger on our .Net APIs. I need to have a look at Swashbuckle.

You may want to take a look at Swagger-Codegen (https://github.com/swagger-api/swagger-codegen) as well to generate ASP.NET 5 server stub or C# API client given a Swagger/OpenAPI spec.

Disclosure: I'm a top contributor to swagger-codegen

Another cool thing (potentially) about swagger is that AWS is supporting it for their API Gateway. You scan write a spec in swagger, tie it to AWS Lambda "functions", and AWS will create/update that . Still a WIP though :(

Is this the project you are referencing? https://github.com/awslabs/aws-apigateway-importer

If you've a Swagger/OpenAPI spec, you can use Swagger Codegen (https://github.com/swagger-api/swagger-codegen) to generate API clients (SDKs) in C#, Ruby, PHP, Java, ObjC, etc. Here is an example: https://github.com/wing328/petstore-php

A good starting point is to generate the SDK online: https://github.com/swagger-api/swagger-codegen#online-genera...

Swagger-Codegen can also generate server stub in SpringMVC, PHP Slim and more.

Disclosure: I'm a top contributor to the project.

Do you know any projects that reverse this functionality (generating API documentation from code)? I know that https://github.com/timothycrosley/hug intends to provide this in the future, but could not find one for other languages (Javascript would be useful right now).

WSDL is probably the best option, honestly. People will laugh but there are good implementations for all major languages.

Personally I use thrift. I think that's the most fit-for-purpose way of doing it. But many people object to any standard that's not purely HTTP-based.

It seems like a lot of APIs are created to support websites, and then developers/PMs think oh well might as well open this up to the public, not really taking into account the ramifications.

Reply on news.ycombinator.com