Jun 11, 2013 - Most methodologies are born out of the Web Application. Description Language ... You develop your Web ser
API Providers Guide API Design Prepared By Kin Lane June 2013
Table of Contents Overview of API Design Space Building Blocks of API Design API Design Tools Companies Who Provide API Design Services The Future is Bright for API Design
Overview of the API Design Space In the early days APIs were just about deploying and consuming. You were doing one or the other. Then came API management from providers like Mashery, then 3Scale and recently Apiphany. In 2013 the API universe is expanding at a breakneck pace, and API design is coming front and center with new approaches, tools and even companies stepping up to provider services. I define the world of API design as everything that goes into planning and designing your API, as well as the definition of your API that will eventually become your production API, drive your documentation and generate the code samples your developers will use to integrate. Depending on our needs, API design may begin with learning about HATEOAS as part of your design constraints, or API design might simply be about generating a Swagger definition so you can generate interactive API documentation. Ultimately your API design will be the definition of each endpoint, its methods, fields and much more. In a technical sense it is a JSON or XML blueprint that describes your API, and in a creative sense, API design is an art and can possess a strange technical beauty and speak to the value it delivers to endusers. Thoughtful API design early on can save you a lot of mistakes down the road. This project is not meant to endorse any particular approach or methodology, but provide a single resource where you can find the best information on API design. This API design project will be an open source repository containing the building blocks of API design, tools for assisting you in your API design, and companies that provide services in the area of API design. This is a living project, that will be updated weekly. If you know of missing building blocks, or tools and services that should be included, send them to
[email protected]
Building Blocks of API Design There are some common building blocks emerging from the world of API design. When it comes to APIs there is no shortage of passionate opinions about how APIs should be designed and the why behind it. The goal of this research of this project is to identify common building blocks that can help new and existing API providers understand the different existing and new approaches to API design. Building blocks are about assembling API design concepts into modular, bitsize chunks, accompanied by reference URLs, in an effort to educate and prepare you, for your own API design efforts.
API Description There are several ways to descibe API, establish programmatic definition of the API, its endpoints, parameters and other values. Most methodologies are born out of the Web Application Description Language (WADL), such as Google Discovery Documents, I/O Docs from Mashery and Swagger from Reverb. Whle WADL used XML, the newer approaches tend to use JSON. The reason to define your API can vary, but most companies are defining their APIs to create to generate what is known as interactive API documentation and to autogenerate code samples in a variety of language.
HATEOAS HATEOAS, an abbreviation for Hypermedia as the Engine of Application State, is a constraint of the REST application architecture that distinguishes it from most other network application architectures. The principle is that a client interacts with a network application entirely through hypermedia provided dynamically by application servers. A REST client needs no prior knowledge about how to interact with any particular application or server beyond a generic understanding of hypermedia. Contrast this with e.g. a serviceoriented architecture (SOA), where clients and servers interact through a fixed interface shared through documentation or an interface description language (IDL).The HATEOAS constraint serves to decouple client and server in a way that allows the server to evolve functionality independently.
API Design Tools There are tools emerging from some of the API design work going on in the wild. Right now, many of the API tools seem to be focused on generating API definitions in various JSON formats, aiming to assist in API deployment, documentation and management, but with the growth of discussion and evolution of API design concepts like hypermedia or HATEOAS, the amount of tooling is only going to increase. Generally these tools are open source repositories that are stored at Github. The goal is to empower you, the API provider, with the tools you will nee to be successful without incurring additional costs, while you are trying to grow and evolve your API design strategy.
Apiary API Blueprint API Blueprint is lightweight, documentation oriented domain specific language (DSL) for easily designing, building and documenting REST API.API Blueprint is a Markdown.It is easy to learn and read, perfect for comprehensive documentation but also for quick prototyping and collaboration. details.
Apiary Blueprint Parser A JavaScript parser ofApiary API blueprints. Uses Node.js then in browser, include the browser version of the parser in your web page or application using the <;script>; tag. To parse an API blueprint, just call the parse method and pass the blueprint as a parameter. The method will return an object representing the parsed blueprint or throw an exception if the input is invalid. details.
Enunciate Enunciate is an engine for dramatically enhancing your Java Web service API. It's simple. You develop your Web service API using standard Java technologies and attach Enunciate to your build process. Suddenly, your Web service API is boasting some pretty impressive features. Enunciate is an opensource project, licenced under the Apache License, version 2.0.Provides ull HTML documentation of your services, scraped from your JavaDocs. Clientside libraries (e.g. Java, .NET, iPhone, Ruby, Flex, AJAX, GWT, etc.) for developers who want to interface with your API, as well as interface Definition Documents (e.g. WSDL, WADL, XMLSchema, etc.) details.
I/O Docs I/O Docs is a live interactive documentation system for RESTful web APIs. By defining APIs at the resource, method and parameter levels in a JSON schema, I/O Docs will generate a JavaScript client interface. API calls can be executed from this interface, which are then proxied through the I/O Docs server with payload data cleanly formatted (prettyprinted if JSON or XML). details.
Swagger Core Swagger is a specification and complete framework implementation for describing, producing, consuming, and visualizing RESTful web services. The overarching goal of Swagger is to enable client and documentation systems to update at the same pace as the server. The documentation of methods, parameters and models can be tightly integrated into the server code, allowing APIs to always stay in sync. details.
Companies Who Provide API Design Services Most API design work is done by companies in support of their own API programs, we see API design definitions coming from Google, Wordnik and others. But as the space expands there are new companies emerging. Halfway through 2013 I only have a single company on my radar, but I have heard rumors of other companies looking to build services that target the API design space.
Apiary.io Apiary.io wants to make developing and implementing APIs a quicker process. Apiary.io site says they will also help you describe, test, manage and share your API with developers. I feel that API deployment services is a huge opportunity in this space, its good to see a provider step up that will help API owners deploy their APIs, as well as manage them. Apiary.iois still in private Beta, so I can't take it for a spin yet. It will be interesting to learn more about what this latest API service provider can bring to the table. details.
The Future is Bright for API Design Good API design practices, tools and services have a major impact downstream within API initiatives. As more companies reach a maturity point with their API efforts, the desire to refine API design before incurring the costs associated with deployment and management, while working to mitigate risks is increasing. API design has been historically hitched to RESTful dogma and early technologists vision of API discovery. As the API world matures, API design is also becoming about deployment, scalability, syndication, IDE integration, documentation, code samples and overall all the essential building blocks of a healthy API ecosystem. API management providers are building API design tools into their offerings, and as we approach 10K APIs on ProgrammableWeb and the introduction of new API marketplaces like APIhub, Mashape and theRightAPI, the need for consistent API design is nearing a critical point. API design should be first and foremost about delivering quality, consistent and meaningful API endpoints, while also delivering value for discovery, documentation and integration. But we also will see specific industries realize their role in leading API designhealthcare, transportation fleet management, travel, entertainment and other industries will help define acceptable API design standards for their industries through partnerships and from leading by example in their operations. This research project into API design is meant to identify the evolving building blocks, tools and companies that are contributing to the sector. More resources are provided below as an appendix, but all resources are published weekly to Github at design.apievangelist.com and published as this white paper to provide the largest possible reach for this valuable information. The API industry has come of age, and the future is bright when it comes to defining best practices and providing tools that will assist companies and developers achieve the best possible API design.
www.apievangelist.com
[email protected]
Appendix A: Curated News and Resources Designing Hypermedia APIs from www.designinghypermediaapis.com on 6/11/2013), full resource available at http://www.designinghypermediaapis.com/ API Design Wiki from wiki.apidesign.org on 6/11/2013), full resource available at http://wiki.apidesign.org/wiki/Main_Page Web API Design Cookbook from www.w3.org on 6/11/2013), full resource available at http://www.w3.org/TR/apidesign/ Stop Designing Fragile Web APIs by Mathieu Fenniak from mathieu.fenniak.net on 4/29/2013), full resource available at https://mathieu.fenniak.net/stopdesigningfragilewebapis/ White House API Standards from github.com on 4/26/2013), full resource available at https://github.com/WhiteHouse/apistandards Three Ways to Think About API Design from blog.programmableweb.com on 4/26/2013), full resource available at http://blog.programmableweb.com/2012/02/14/threewaystothinkaboutapi design/ REST API Design Rulebook from shop.oreilly.com on 4/26/2013), full resource available at http://shop.oreilly.com/product/0636920021575.do API Design and Architecture Boot Camp from Layer 7 from www.layer7tech.com on 4/26/2013), full resource available at http://www.layer7tech.com/services/apidesignandarchitecturebootcamp API Design and Documentation from www.howto.gov on 4/26/2013), full resource available at http://www.howto.gov/mobile/apisingovernment/apidesigndocumentation API Design from Apigee from apigee.com on 4/26/2013), full resource available at http://apigee.com/about/apibestpractices/apidesign/all How to Design a Good API & Why it Matters from www.infoq.com on 4/26/2013), full resource available at http://www.infoq.com/presentations/effectiveapidesign Designing APIs for Humans from johnsheehan.com on 4/25/2013), full resource available at http://johnsheehan.com/post/48863654793/designingapisforhumans API Design & Development Guidelines from www.dzone.com on 2/16/2013), full resource available at http://www.dzone.com/links/r/api_design_amp_development_guidelines_selected_re.html API Design from Apigee 3rd Edition from blog.apigee.com on 1/16/2013), full resource available at https://blog.apigee.com/detail/api_design_third_edition_video_slides OData and Impact on API Design (video & slides) from blog.apigee.com on 6/3/2012), full resource available at https://blog.apigee.com/detail/odata_and_impact_on_api_design_video_slides/ API Design by Matt Gemmell from mattgemmell.com on 5/24/2012), full resource available at http://mattgemmell.com/2012/05/24/apidesign/
