API Best Practices Blog
We want to build better tools for API developers. Will you help? »
Apigee constantly strives to better serve the needs of developers and to that end, it’s time for us to conduct a usability review of our existing toolset.
If you have spent time making an app talk to an API, and can come by our Palo Alto offices next week, then we'd love to hear from you:
https://www.surveymonkey.com/s/KZH96KW
If you are selected, you’ll get a $150 AmEx gift card to help offset travel expenses (and a lifetime of gratitude from developers everywhere).
Apigee v2 Console: Making learning APIs as simple as possible, but no simpler »
The most delightful learning experiences are natural and effortless. With that in mind, we at Apigee strive to minimize the time it takes to make your first successful API request.
We make it as simple as possible to learn how to make successful API calls, but don’t prevent you from purposefully making failing requests, which can be useful while troubleshooting. Read on!
In the v2 Console, there are three new features that make it simple for you to learn an API.
Contextual Help
Let’s face it, nobody likes documentation until they get stuck and then, only as much as they need to get their work done. For a long time, people have asked us for deep-linked documentation right in the console. API Providers can now add summaries and deep-links to every method and parameter in the Console and API Resource pages.
In many cases, you have all you need to know to make a successful API request right in the Console but if that’s not enough, you can go directly to the full documentation at the API provider’s site.
Parameter Surfacing
Even the best APIs can be complex to learn. We’ve made it even easier to make a successful API request by surfacing all of the parameters in an intuitive way. In most cases, you can choose an API provider (1), select the service (base URI) (2), and method (4) you want to work with and send the request.
You’ll see right away if the method requires authentication (3) or parameters (5) and you can add those as well.
You are alerted if you are missing any of the required parameters as shown below.
All of the parameters defined in the API should automatically be listed in the appropriate query tab including:
Query parameters: In this query the alt parameter is set to ‘atom’.
In this case, the API specifies that this must be one of 5 types and all are shown in a drop-down menu. This would show up in the request as
http://gdata.youtube.com/feeds/api/users/apigee?alt=atom&prettyprint=true&v=2
where alt=atom is a drop down and prettyprint=true is a Boolean value in the Query tab.
You can additionally add any custom name/value pairs to the query of the API request.
Template parameters: are associated with parameters in the URI path. In the example above, {username} is a template parameter and can be provided in the Template tab.
This is a required field as noted by the asterisk. You can additionally add any custom name/value pairs to the query of the API request.
Header parameters: are your chance to modify the headers of the request. user-agent is a very common choice and we’ve provided it for you so, for example, you can simulate sending the request from an iPhone or Android device.
You can additionally add any custom name/value pairs to the Header of the API request.
Body parameters: are typically for an attachment like uploading a video or picture or an XML, or JSON payload.
While we’ve made it easy to make successful API requests, we don’t prevent you from purposefully making failed requests. These are often helpful in isolating problems. As simple as possible, and no simpler!
Bookmarking API Requests
Another new feature of the v2 Console is the ability to bookmark API requests complete with the method and every parameter. This allows you to to repeat a range of test cases or share a particular API query in a blog.
For example, say I wanted to instruct you on the Youtube /feeds/api/users method. I could simply provide a link and it would load the console ready to make the request. Go on, try it.
As you can see, this will give you a list of great Apigee videos in atom format. This can also be used by API providers to make it easy for developers to instantly try examples from their reference documentation, on discussion boards, or email threads.
These are just a few of the great features included in the new v2 Console. With over 60 API providers, there are a lot to choose from.
If you would like a Console for an API that you don’t see, please send an email to .(JavaScript must be enabled to view this email address). You can use the Generic/Other console which allows you to send any REST request.
New Release - API Developer Tools »
I'm delighted to announce that a new release of our Developer Tools. Actually, we've been plugging away on releases on a monthly basis for the last 6 months and now it has really come together. Seriously, there are some huge changes. A short summary is provided below.
The console speaks for itself. We have indeed been "working" and below the picture are the release highlights.
All new features!
- All Resources are surfaced to the user along with indication of which require authentication and deep-links to the API Provider's doc. All of this is generated from the WADL. This is a great step for both API providers wishing to make their own To-Go Console and for Developers.
- We automatically surface all of the parameters for every resource through the GUI along with parameter-level docs with links if we have them.
- Users can set the user-agent for requests.
- Support for WADLs with multiple end points in the same Console. Better for providers and easier developers to use.
For example:
api.twitter.com
search.twitter.com
statuses/{id}/retweeted_by,
{id}
is a template param.
- Bookmark Console requests. Yes, you can save all the settings and parameters to make a request.
For example, say I wanted to instruct you on the Youtube /feeds/api/users method.
I could simply provide a link and it would load the console ready to make the request. Go on, try it!
As you can see, this will give you a list of great Apigee videos in atom format.
This can also be used by API providers to make it easy for developers to instantly try examples from their reference documentation, on discussion boards, or email threads.
- Compression of WADLs to improve page load time. We are going to be working quite a bit more on performance.
We also included a large number of upgrades and bug fixes:
- Upgrades to Providers page; improved navigation and more.
- Bug fixes: hundreds over the last few months.
- V2 Console Migration
- All but one of our Consoles has been moved to our v2 platform!
- New! v2 Support following authentication schemes: HTTP Basic Auth, Custom Token, Two-legged OAuth, and OAuth refresh token.
- Resolved Google Authentication issues enabling all of the Google Consoles
- 5 Refreshed Consoles
Consoles
As of this writing, we have 62 Consoles. You can see the full list of API Providers in HTML or use our Console API.
Have a desire to see an API included that we don't have? Send requests to .(JavaScript must be enabled to view this email address).
New Consoles
BlueVia
BoxCar
Context.io
DonorsChoose.org
Echonest
Facebook (added the Search endpoint)
Foursquare
Google AdSense (Management)
Google Analytics
Google Books
Google Calendar
Google Latitude
Google Mail (Settings)
Google Sites
Google Spreadsheets
Google Tasks
Milo
MusicBrainz
Myspace
Orkut
Picasa
Rdio
Rhapsody
Sendgrid
Spotify
Tumblr
Updated Consoles. APIs are best served fresh!TM
Urban Airship
Usergrid
Weather Underground
Yahoo Weather
YouTube
Tumblr
The Anatomy of Apps »
Thanks to all who participated in last week's strategy webinar:
The Anatomy of Apps - How iPhone, Android & Facebook Apps Consume APIs
Thanks to our speakers @edanuff, @landlessness and @sramji.
Here are the slides and video. We'd love more of your thoughts, insights, or questions on the api-craft forum. Or tune in to the new IRC channel #api-craft.
A look at the BlueVia Developer Platform »
BlueVia, a global developer platform initiative of Telefonica, has partnered with Apigee to provide the BlueVia API console for developers to explore and test their APIs.
So we asked them to sit down with us to tell us a little about BlueVia. In this video, BlueVia's Dan Appelquist and Jose Valles discuss the BlueVia Platform with Jeremy Perlman of Apigee.
Tune in to learn what BlueVia is, how the platform provides access to Telefonica's assets and helps developers take apps, web services, and ideas to market.
And it's BlueVia's first birthday and they're celebrating by giving developers a chance to win a MacBook Air and Samsung Galaxy Nexus. Check the BlueVia blog for details.
BlueVia Developer Platform
The SMSified REST API Explorer »
Voxeo Labs, the creators of SMSified and other innovative communications services and technologies, has partnered with Apigee to introduce the new SMSified API Explorer! Developers can explore and experiment with the SMSified REST API without writing a single line of code! Get started with adding inbound and outbound SMS text messaging to your application today.
In this video, Chris Matthieu of Voxeo labs walks you through using the API Explorer to interact with SMSified's SMS REST API.
SMSified API Explorer
Developers Hate Marketing: Launching and marketing your API »
Once you build your API, will developers come?
We've picked up some good stuff from our customers on this topic, many of which we've posted as developer adoption best practices on this blog.
So today we've rolled these in a new whitepaper with our friends at Evolved Media - Developers Hate Marketing: Attracting Developers to your API.
Topics include some thoughts on:
- what do developers expect?
- do's and don'ts in launching your API
- patterns in successful developer programs
You can find it here, we'd love to hear what you think.
Social App Workshop Wrap-Up: A Ton of Developers, a Few APIs, and a Whole Lot of Magic »
This past Saturday we collaborated with Heroku and Twilio to put on Social App Workshop, an all-day hacker event in San Francisco focusing on people building applications with the Facebook and Twitter APIs. Over 130 developers gathered early in the morning to hack, learn and collaborate.
We heard some cool presentations and Twitter launched their bridge code for the @Anywhere service! Documentation is coming soon but you can check out some of it here. The Twitter team had been up working on it until 1:00 am the night before!
Here's some top trends from the event:
1. Simplicity is everything
Presentations by Oren Teich of Heroku on cloud services and hacker advocate Abraham Williams on minimalism in feature design shared a common theme: simplicity is key - both for applications and the infrastructure, tools and languages that are used to build them. With the immediacy of social tech, increasing mobility, and intense app competition, fast and easy is the new imperative.
"Make it as easy to use as possible. Then make it easier." - Oren Teich
"Users are lazy…. Make your web app like AAA - only there when you need it" - Abraham Williams
2. Innovate Faster
A big buzz topic during afternoon coding was the need for speed- and languages, cloud services and developer tools that let people build and deploy applications quick. As presentations on the Twitter API by Matt Harris and the Facebook API by Matt Kelly showed, simple, logical APIs with easy-to-understand structures are a critical element for fast innovation. API providers who align with developers' mission to build-and-deploy in lightspeed are more likely to succeed.
3. The Mashup New School
The concept of "mashups" that combine services and APIs from multiple sources has been around for awhile- but the new school of mashups is all about taking different capabilities from across industries and putting them together to create entirely new functionalities. Take Twilio- which provides an open API for building voice and SMS applications and can bring the world of telephony into your apps. We're seeing more and more industries- health care, 3D, semantic analysis- innovating with APIs and making a whole new school of mashups possible.
4. Ruby is HOT
Social app developers love Ruby! Tons of attendees were either Ruby experts or trying to learn- there was even a "Ruby N00bs" informal group that got together in the afternoon to collaborate on getting up and running. Developers like Ruby because it lets them build fast- especially when combined with cloud platforms like Heroku.
Thanks to everyone who participated! You can see more pictures on Flickr and we hope to see you at an event soon. In the Bay area and have ideas on developer events? Shoot us an @ sign on Twitter.
Social App Workshop for Devs Building Facebook and Twitter Apps »
We're psyched to be working with Heroku and Twilio to organize an an all-day hackfest in San Francisco for developers building applications on the Facebook and Twitter APIs.
Social App Workshop is a one-day coding event for new and experienced developers building social apps. We'll have speakers from the Twitter and Facebook platforms- including Matt Harris from Twitter- and food, drinks, lots of coding time, plus lightning talks from experts on strategies, tools and tactics for creating awesome apps. It'll be at Heroku's new offices in SOMA and we'll be breaking them in!
If you are a new or experienced Twitter or Facebook developer and you'll be around downtown San Francisco on Saturday, July 24, you should come and hang out- it's free and a good chance to learn new things, do some networking and build something cool. Check out the website at http://www.socialappworkshop.com or follow the event on Twitter- http://www.twitter.com/appworkshop.
If you are a new or experienced Twitter or Facebook developer and you'll be around downtown San Francisco on Saturday, July 24, you should come and hang out- it's free and a good chance to learn new things, do some networking and build something cool. Check out the website at http://www.socialappworkshop.com or follow the event on Twitter- http://www.twitter.com/appworkshop.
If you are a new or experienced Twitter or Facebook developer and you'll be around downtown San Francisco on Saturday, July 24, you should come and hang out- it's free and a good chance to learn new things, do some networking and build something cool. Check out the website at socialappworkshop.com or follow the event on Twitter- twitter.com/appworkshop.
The Echo Nest Remix API- Literally Music to the Ears »
Every now and then at Apigee we run into an API that is so brilliant, so elegantly inventive; an API that elevates mankind, changes the way we see the world, and renews our obsession with making a better way to API.
The Echo Nest Remix API is an internet synthesizer API. It lets you do amazing things with music and video, like write remix programs, sync videos to songs, mashup audio tracks and more. It's currently available as an open source SDK for Python- more languages soon- and is easy to install on OSX, Windows and Linux/Source.
We've had some fun this morning playing with different implementations of the API; like cowbell-ifying Led Zeppelin's Babe I'm Gonna Leave You with http://morecowbell.dj/ and listening to samples from "The Swinger", which takes each beat, time-stretching the first half while time-shrinking the second half to make swing from any song you can think of.
We also like how the Remix API provides a list of example implementations to inspire and help people learn- great best-practice for API providers.
See any mind-blowing APIs we should know about? Leave a comment or tweet at us: www.twitter.com/apigee
WWSJD- What Would Steve Jobs Do? Lessons for the Age of APIs »
Zen and the Art of an API Ecosystem: Building Platforms Through Partnership »
This week MySpace launched the Developer Services program to make it easier for developers on their API to use cool tools for creating, deploying and managing their apps. Through the new portal, developers get better and discounted access to frameworks, hosting, monetization and mobile tools and analytics. We're excited to be one of the partners along with services like PushButton Engine, Microsoft BizSpark and PayPal.
The Developer Services program highlights the new business imperative for API providers- building an ecosystem- and the ways partnerships support that goal.
From Tech to Platform
An open API isn't just about making a technology available- it's about building a platform. The new web economy means billions of devices, millions upon millions of users and thousands of APIs. When your API is deeply hooked into the fabric of the internet, the developer world and the ongoing evolution of tools, devices and services, it gains both greater immediate value and longevity.
Developers are going to use your API with other APIs, they're going to use monetization and analytics tools, and they're more and more likely to use cloud services that make it easy to scale their stuff. There's a growing opportunity for API providers to form partnerships that simultaneously simplify and improve the development process while enriching the API ecosystem.
This approach to community and ecosystem is both philosophy and business strategy- a belief that empowering developers to access the tools they want is beneficial to all; and a model that supports adoption, innovation and ROI.
Apigee API Contest Winner at iPad Developers Camp - Netflix Actors »
The winners of the Apigee sponsored prize at the iPad developers camp was the "Netflix Actors" application. Check out a quick demo of the application below.
The Snow Report from the North Face: iPhone API monitoring »
As a bunch of skiers, we were excited to see the this app's traffic taking off when our first early winter storm moved in.
The Snow Report from the North Face gives you the best ski conditions around the world, while making it easy to quickly focus on what's local through favorites.
We love the UI, feature set, and use of notifications in this app. The Twitter integration is killer - is a great way to plug into what's really happening so you can doublecheck the official reports.
FactoryLabs - the app developers - use Apigee to monitor API performance and usage for snow conditions, weather, and other data. They've had great feedback on Apigee - specifically, we'll eventually let you specify fields in the payload that help you ID the developers or consumers using your app.
We'd love to hear what's on your wish list also on our feedback forum and in the meantime check out the app!
