API Adoption Tip: One simple, open method »

Whether you are creating an API for internal use, partners or the wide open world of application developers -  here is a tip that could help with initial adoption of your API.

Create at least one simple, open API method.

What I mean by simple and open is an API satisfying these criteria:

• no signup required
• no authentication required
• uses HTTP GET
• returns JSON

A good example - is the the Twitter public timeline API method - no signup or authentication required.

Many API teams we work with are creating sophisticated, highly secure APIs with complex authentication and authorization requirements. The API's primary purpose is to access private, secure data.

Why would an API team working on such private stuff take the time to create at least one simple, open API method? Adoption.

If a developer can copy and paste a simple URL into his browser and see JSON coming back then he's already used your API. If he's already a user then getting him to sign up and figure out authentication will be easier for him to stomach.

How do you find an appropriate API method to create?

One place to start is your company's website. Maybe it has a listing of the products and services you sell? Or the people on the management team?

Find some information that is already publicly available and wrap an API around it. Your developers will thank you by using it, signing up and creating compelling apps.

For more on developer adoption - check out our new webinar video on Developer marketing and adoption How-Tos and best practices

Need API and developer adoption?  Try a Hack Day! »

Want to launch your API with a bang?  Or get more internal adoption?

Hack Days (or Hackathons) give developers a day off to build anything they can dream up. No rules. At the end of the day, developers demo for glory and free beer.

Check out the recent FourSquare Hack Day. LinkedIn had a great one. And there are independent Hack Days.

If your API is only available to developers inside the company - even more reason. Why?

- Get the word out - Hack Day is a high profile way to drive adoption and build grass-roots excitement internally.

- Showcase innovation - with great new Hacks and product ideas you'd never have thought of.

- Get those example apps! -  need example apps and code on your developer portal?  Don't DIY or pay someone -use the best Hacks!

- Eat your own dogfood -  Find bugs before releasing your API to partners.

-Get recruits! -   Need good hires for the API team but don't want to ask?

Here are a few tips:

- Dedicate time  - give developers a full day with no distractions.  

- Team up!   Encourage developers to team up and mix skillsets.  

- Demo for glory.  Get your CEO and execs to judge demos at day's end.   The Hack doesn't have to be finished.  Prizes are nice but recognition might be enough.

- Feed me!  Beer and free food can take a OK Hack Day and make it a *great* hack day.

- Start small, but rinse and repeat.  Your first Hack Day might be small and a little rough.  Buy the 3rd or 4th time - you might have Beck playing on your lawn.

- Productize!  Have a labs page or a way to turn great hacks into real product.  

- Provide tools.  Give your developers an API console to learn your new API and debug API problems.

(Thanks to SimpleGeo for the image above)

Design your API for adoption with ‘true REST’ »

"The only reason you'd have only a SOAP API is because you hate 80% of your addressable market." - @sramji

There's usually little argument that a REST API is easier to use than a SOAP API.

But how important is it to be 'truly' or 'strictly' RESTful? That is, adhering to standard HTTP operations or 'verbs' - GET, PUT, DELETE, POST - on well defined resources, as opposed to the common practice of embedding 'verbs' or operations as methods in a GET URL.

Typically, security is cited as the big advantage of 'true REST' (with some good discussions here and here).

However, a truly RESTful API may help you boost developer adoption. For example, imagine a 'shopping cart' API:

While the above API isn't 'truly RESTful', it's not that hard to use.  But you do have to learn the individual operations and this can get cumbersome if there are a lot of them or as the API evolves.

Instead, this 'true REST API' may be easier to learn and predict as you use more features.

What if we want to list all the shopping carts in the system at any one time? We would add that via an HTTP GET to:

http://api.shopping.com/carts.xml

Query parameters can still serve a purpose - making it possible to specify additional options. For instance, imagine a very large shopping cart, and you want to "paginate" the results. To look at items 20-29, you might use a URL like:

http://api.shopping.com/carts/X.xml?start=20&;count=10

Bonus: True REST makes analytics easier

It's a lot easier to build reports that segregate and analyze traffic by URL than to build logic that tries to do this by methods or combination of methods. Good API analytics helps you optimize features, debug problems, and weed out traffic that can slow down your service.

What if your 'non-strict' REST API is already out there?

It might not be that big a deal if your API is very simple or 'read-only' API with information that isn't too sensitive (such as a free search API). Or you can map a non-RESTful API into a 'truly RESTful" API with custom code or API management tools thatperform API transformations.

* A note on POST VS. PUT

* One way to insert an item in the shopping cart is to use POST to update the shopping cart by sending it a new item. In this case, we are using POST to send the server an instruction that essentially tells it to insert some new content to the existing resource. This is why we use POST -- it is like an "update" in a database.

Alternately, we could add the item by using PUT to a new URL, such as:

PUT http://api.shopping.com/carts/X/items/Y.xml

But if we do this, then we need to somehow give our item some sort of unique URL by picking a value for "Y". This is kind of a strange thing to do, so it may be more natural to use POST and have the response include the URL for the new item, so that we may retrieve it later using GET or delete it using DELETE. Still, sometimes using PUT like this makes sense.

This all comes down to the difference between PUT and POST in the HTTP spec. POST modifies something that already exists, and how that thing is modified is up to the server. PUT replaces the entire contents of the URL with new data. Plus, like GET, HEAD, and DELETE, PUT is idempotent, which means that if you call it more than once, it has the same result every time, whereas POST may keep doing what you ask it to do over and over again

Mobile Location-Based Services - don’t forget the Telcos »

TechCrunch recently posted on a Juniper report on “Mobile Location Based Services"  This report taps on the potential for this new wave of powerful apps – like letting your phone geotag the video you just took and posting it to Facebook with a Google Maps link;  one-button dial to a nearby restaurant discovered through your social network; or dynamically billing for high-value media content via the operator.  

Companies like Google, Foursquare, and Nokia are mentioned as on the forefront of many of these services.

But don't forget the Telcos - they have rich location based services with network data and a huge customer base.  Exposing APIs and working with third party content and service providers is critical for telcos and network operators. 

But Telco APIs can be complex.  Our view is that the Telcos that focus on making these APIs as simple and accessible as those from consumer Web players can be winners in MLBS.  We talk about these and other issues in detail in our new Telco 2.0 Whitepaper.