{"API Definitions"}

API Monitoring Blog Posts

These are posts from the API Evangelist blog that are focused on API monitoring, allowing for a filtered look at my analysis on the topic. I rely on these posts, along with the curated, organizations, APIs, and tools to help paint me a picture of what is going on.

The Potential Of The OpenAPI Spec Parameters Object

I enjoy learning from the OpenAPI Specs of the API providers I track on. Just having an OpenAPI Spec present tells a lot about an API provider in my book, but the level of detail some providers put into their API definitions adds another level to this for me. While reviewing the OpenAPI Spec for the Oxford Dictionaries API, I noticed their robust usage of the OpenAPI Spec parameters definitions collection, which provides an interesting overview of the surface area of the API, augmenting the benefits brought to the table by the definitions collection of an APIs underlying data schema.

When you are defining each path for an API you can either define the parameters using each paths parameters, or you can add them to the overall parameters definition object, allowing them to be reused across all paths. This object provided me with a centralized place to learn about the parameters used when making calls to the Oxford Dictionary API, and I'm assuming it helped them be more organized in how they defined the surface area of their APIs.

I can see how the processing of defining each path's parameters, and centrally organizing them for reuse can be a healthy thing. The more you lift yourself out of the individual definition of each path and consider the parameter patterns that have been used for other paths, the chances you will have a better view of the landscape will increase. I am optimistic about this OpenAPI Spec object, and curious about how it can be evolved as part of other conversation around GraphQL--something I'll work to understand better in the future.


OpenAPI Spec Google Spreadsheet to Github Jekyll Hosted YAML

I have been playing around with different ways of using Google Spreadsheet to drive YAML and JSON data to Jekyll data projects hosted as Github repositories. It is an approach I started playing around with in Washington DC, while I was helping data stewards publish government services as JSON-LD. It is something I've been playing around with lately using to drive D3.js visualizations and even a comic book.

There are couple of things going on here. First, you are managing machine-readable data using Google Spreadsheets, and publishing this data as two separate machine readable formats: JSON and YAML. When these formats are combined with the data capabilities of a Jekyll website hosted on Github Pages, it opens up some pretty interesting possibilities for using data to fuel some pretty fun things. Plus...no backend needed.

To push this approach forward I wanted to apply to managing OpenAPI Specs that can be used across the API life cycle. I pulled together a spreadsheet template for managing the details I need for an OpenAPI Spec. Then I created a Github repository, forked my previous spreadsheet to YAML project, and modified it to pull data from a couple of worksheets in the Google Doc and publish as both JSON and YAML OpenAPI Specs. 

My OpenAPI Spec Google Sheet to YAML for use in a Jekyll project hosted on Github is just a prototype. The results don't always validate, and I'm playing with different ways to represent and manage the data in the Google Sheet. It is a fun start though! I am going to keep working on it, and probably start a similar project for managing an APIs.json index using Google Sheets. When done right it might provide another way that non-developers can participate in the API design process, and apply OpenAPI Specs to other stops along the API life cycle like with API documentation, SDK generation, or testing and monitoring.


Please Share Your OpenAPI Specs So I Can Use Across The API Life Cycle

I was profiling the New Relic API, and while I was pleased to find OpenAPI Specs behind their explorer, I was less than pleased to have to reverse engineer their docs to get at their API definitions. It is pretty easy to open up my Google Chrome Developer Tools and grab the URLs for each OpenAPI Spec, but you know what would be easier? If you just provided me a link to them in your documentation!

Your API definitions aren't just driving the API documentation on your website. They are being used across the API life cycle. I am using them fire up and playing with your API in Postman, generating SDKs using APIMATIC, or creating a development sandbox so I do not have to develop against your live environment. Please do not hide your API definitions, bring them out of the shadow of your API documentation and give me a link I can click on--one click access to a machine-readable definition of the value your API delivers.

I'm sure my regular readers are getting sick of hearing about this, but the reality of my readers is that they are a diverse, and busy group of folks and will most likely not read every post on this important subject. If you have read a previous post on this subject from me, and are reading this latest one, and still do not have API definitions or prominent links--then shame on you for not making your API more accessible and usable...because isn't that what this is all about?


The Different Reasons Behind Why We Craft API Definitions

I wrote a post about the emails I get from folks telling me the API definitions contained within my API stack research, something that has helped me better see why it is I do API definitions. I go through APIs and craft OpenAPI Specs for them because it helps me understand the value each company offers, while also helping me discover interesting APIs and the healthy practices behind them.

The reason I create API definitions and organize them into collections is all about discovery. While some of the APIs I will be putting to use, most of them just help me better understand the world of APIs and the value and the intent behind the companies who are doing the most interesting things in the space.

I would love it if all my API definitions were 100% certified, and included complete information about the request, response, and security models, but just having the surface area defined makes me happy. My intention is to try and provide as complete of a definition as possible, but the primary stop along the API lifecycle I'm looking to serve is discovery, with other ones like design, mocking, deployment, testing, SDKs, and others following after that.

Maybe if we can all better understand the different reasons behind why we all craft and maintain API definitions we can better leverage Github to help make more of them complete. For now, I'll keep working on my definitions, and if you want to contribute head over to the Github repo for my work, and share any of your own definitions, or submit an issue about which APIs you'd like to see included.


APIs Can Give An Honest View Of What A Company Does

One of the reasons I enjoy profiling APIs is that they give an honest view of what a company does, absent of all the marketing fluff, and the promises that I see from each wave of startups. If designed right, APIs can provide a very functional, distilled down representation of data, content, and algorithmic resources of any company. Some APIs can be very fluffy and verbose, but the good ones are simple, concise, and straight to the point.

As I'm profiling the APIs for the companies included in my API monitoring research, what API Science, Apica, API Metrics, BMC Software, DataDog, New Relic, and Runscope offer quickly become pretty clear. A simple list of valuable resources you can put to use when monitoring your APIs. Crafting an OpenAPI Spec allows me to define each of these companies APIs, and easily articulate what it is that they do--minus all the bullshit that often comes with the businesses side of all of this. 

I feel like the detail I include for each company in an APIs.json file provides a nice view of the intent behind an API, while the details I put into the OpenAPI Spec provide insight into whether or not a company actually has any value behind this intent. It can be frustrating to wade through the amount of information some providers feel they need to publish as API documentation, but it all becomes worth it once I have the distilled down OpenAPI Spec, giving an honest view of what each company does.


SchemaHub's Usage Of Github To Launch Their API Service Is A Nice Approach

I'm looking through a new API definition focused service provider called SchemaHub today, and I found their approach to using Github as a base of operations was interesting and provided a nice blueprint for other API server providers to follow. I'm continually amazed at the myriad of ways that Github can be put to use in the world of APIs, which is one of the things I love about it.

As a base for SchemaHub, they created a Github Org, and made their first repository the website for the service, hosted on Github Pages. In my opinion, this is how all API services should begin, as a repo, under an organization on Github--leveraging the social coding platform as a base for their operations.

SchemaHub is taking advantage of Github for hosting their API definition focused project--free, version controlled, static website hosting for schemahub.io. 

As I was looking through their site, learning about what they are doing I noticed a subscription button at the bottom of the page, asking me to subscribe, and they'll notify me when things are ready.

Once I clicked on the button, I was taken for a Github OAuth dance, which now makes SchemaHub not just a Github repo for the site, it is an actual Github Application that I've authenticated with using my Github account. They only have access to my profile and email, but is the types of provider to developer connection I like to see in the API world.

Once I authorize and connect I am taken to a thank you page back on their website, letting me know I will be contacted shortly with any updates about the service. Oh, and I'm offered a Twitter account as well, allowing me to stay in tune with what they are up to--providing a pretty complete picture for how new API services can operate. 

SchemaHub's approach reflects what I'm talking about when I say that Github should offer an Oauth service, something that would enable applications running on Github to establish a Github app as part of their organization and website. I like this model because it enables connections like Schema has established to occur, maximizing the social powers of the Github platform.

SchemaHub wins for making a great first impression on me with their API service. Github Org, simple static Github Pages hosted website, connectivity with my Github profile, and a Twitter account to follow. Now I know who they are, I'm connected, and when they are ready with their API service, they have multiple channels to update me on. My only critique is that I would also like to have a blog with Atom feed, so I can hear stories about what they are trying to accomplish, but that is something that can come later. For now, they are off to a pretty good start.


Defining API Surface Area By Converting HTML Forms To Open API Specs

I'm investing some time learning about the USGS Water Services. They have some pretty interesting APIs, providing access to a wealth of data about water table levels, river flows, and other key points across all USGS sites. While their developer area has a wealth of information available, it is also pretty verbose and tough to absorb.

I wanted to help make the information more accessible, filterable, and remixable by turning it into an OpenAPI Spec. It is A LOT OF WORK to craft a complete OpenAPI Spec for a robust API like the six that are available from the USGS. One way I help alleviate this work is to scrape API documentation. As I was preparing to do this I noticed they also have testing tools for 5 out of the 6 APIs, which are just HTML forms containing a definition of the surface area for each API. 

The HTML forms provide me with a slightly more structured definition of each API so I will start here. Once I've ingested these, I will write a scrape script for the HTML API documentation, and link the two up. Once I'm done with this I will be able to generate an OpenAPI Spec that is halfway complete (with just the surface area). Once I have this I can load up in my Postman client, turn on Charles Proxy and my internal API monitoring system will fill in the remaining definitions for the Open API Spec--now I have the request and response model, in a machine readable format. 

As I write the code to tackle this, I'm thinking about what a great approach HTML forms are to helping both technical, and semi-technical HTML craftspeople define the surface area of an API. Then I think about my friend Mike Amundsen (@mamund) and his work on ALPS, and I smile, and I'm reminded of how much work we have ahead of us when it comes to both web literacy and establishing more meaningful, reusable design patterns across the API space(that repo should be full).

P.S. Is there a better tool out there for turning HTML Forms into OpenAPI Spec or at least JSON or YAML?
P.S.S. If you wanna create an API that I can pass any web page with a form in it, and get back an OpenAPI Spec, you are a good person.


Diff Tooling For JSON, YAML, And Markdown Versions Of API Definitions

As the number of available API definitions out there grows, I am increasingly coming across variations of APIs that I already have included in my API Stack. It can be tedious to try and sync these with existing copies, so I wanted to take a look and see if there was anything already available out there, that would help provide a diff for either OpenAPI Spec, RAML, or API Blueprint.

The most common one I found referenced was a Ruby one for OpenAPI Spec from Civis Analytics. Next, I found a pretty interesting web tool, which provides its Node.js source code on Github, including a CLI edition. After these two solutions, I only found one more for RAML, but couldn't find anything for API Blueprint.

I wanted to think beyond just the common API definition formats and look for diff tools that would work just for JSON. I found Diff which was pretty interesting, as well as DiffSync which provided a real-time diff for JSON. I haven't tried any of them out, I am just trying to compile a list of what is out there before I dive into what their capabilities are.

I have a master database of API definitions where I can just import API definitions that I find, and it will add any new paths, parameters, and schemas it comes across. I would much rather have the ability to just run each version through a diff tool, and be able to select which elements I want to have merged. For now, I will just implement a custom layer to my API monitoring system, but I would like to see API diff move forward similar to we saw the conversation evolve with the introduction of API Transformer.


Cutting Through The Smoke & MIrrors Of IT Discussions Using API Definitions

I get brought into a lot of API discussions with IT departments from companies, institutions, and government agencies, which are often coordinated by business groups who are interested in better meeting their goals using APIs. This is often an immediately charged conversation, with IT coming to their table with a whole array of baggage. 

In about 75% of the situations, IT, and developer representatives are nice, or rather they are tight-lipped, relying on a myriad of smoke & mirrors to defend their dark arts. Let me stop for a moment, and put out there that I was IT director from 1998 through 2010. I'm not saying IT are bad people, but there are a wide variety of ways we slow, obfuscate, and distort the conversation to be in our favor -- takes one to know one. I wouldn't say that I was 100% honest in my approach to being an IT leader, but I tried my hardest to keep things as transparent as I possibly could.

Anyways, in a couple of the  IT discussions I've had lately, there was an OpenAPI Spec available to define the resources that were on the table, and in a handful of other conversation there were not. Keep in mind that most of these scenarios are with a more traditional version of IT, not with startup technology groups (a whole different beast). As I step back, I am taking notice of the harmonizing effect that an API definition can have, in keeping conversations focused, productive, and moving forward toward a common goal.

In the conversations without an OpenAPI Spec, back-end systems and legacy processes dominated the discussion, even though we are all on a conference call to discuss an external, partner, and public facing API. In the discussions where an OpenAPI Spec was present, we focused on exactly which resources were needed (nothing more), and the details (params, responses, etc) that were needed by all consumers--essentially providing us with a scaffolding for the discussion, that kept things moving forward, and not bogged down in legacy sludge. 

Backend focused discussions always seemed to get slowed down by what was, and what is. The API definition focused conversations seemed to focus on what was needed, using a common language that everyone at the table understood. The presence of an OpenAPI Spec seemed to cut through the smoke & mirrors, which I think often alienates many of the business users. I find having three versions of an OpenAPI Spec and APIs.json file present: 1) simple outline 2) YAML and 3) JSON, was also something that significantly improved discussions, keeping conversations focused while also making them as inclusive as possible.

I think people will always bring their baggage to these discussions, but I'm liking the harmonization effects API definitions like OpenAPI Spec, API Blueprint, Postman, and APIs.json are having in these conversations. I'm hopeful that these API definitions can continue providing bridges between business and IT groups, helping close a canyon that has existed for decades.


I Am Seeing Significant Returns From Investing In Definitions Over Code When It Comes To My API Strategy

I am doing way more work on the creation of machine-readable OpenAPI Specs for APIs, indexed using machine-readable APIs.json files than I am the actual creation of APIs lately. About half of the API definitions I create are for existing APIs, with the rest of them describing APIs that should exist. With the existing APIs, in some cases, I am creating client-side code, but mostly just focusing on a well crafted API definition. When it comes to the new API designs, I am focusing on a complete API definition, but also crafting both server-side, as well as client-side code around the definition--when needed.

Even when I do craft server or client code for an API definition, the value of the code is significantly lower than the definition(s). In my mind the code is disposable. I want to be able to throw it away, and start over with anything I am building, at any point. While I have made significant ideological investments into using Linux for my OS, AWS for my compute and storage hosting, MySQL for my database, and PHP + Slim for my API deployment framework, the code that operates within this framework has to be transient. Some code might end up having a long, long life, but if a piece of code isn't generating value, and in the way, I want to either get rid of it or rewrite it to better meet the requirements.

When it comes to delivering technology in my world, my investments are increasingly in the API definitions, underlying data schemas, and the data and content that is actually stored and transmitted within. The PHP, MySQL, JavaScript, CSS, and HTML is valuable, but a second class citizen to the JSON, and YAML representations of my APIs, schemas, and the valuable data and content stored. For me personally, having made significant investments in a variety of tech solutions historically, this provides me with the flexibility I need to live in the current online climate. This is something that only has been coming into focus in the last year, so I assume it will also continue to evolve in focus over the next couple of years, but I am already seeing significant returns from my investing in definitions over the code when it comes to my API strategy.


Example Of API Service Providers Making Onboarding With Services Easier Using API Definitions

API definitions like OpenAPI Spec, API Blueprint, and Postman, have been gaining in popularity over the last couple of years, mostly because of the their ability to deploy interactive documentation like Swagger UI. However, the API providers who have been using them the longest, have also realized these machine readable definitions can be applied effectively at almost every step along a modern API life cycle, from design to deprecation.

I'm always encouraging companies, who are selling software services to the API space (aka API service providers), to make sure and have APIs for their entire stack, as well as speak in as many of the leading API definition formats as you possibly can. To help in this effort, I try to regularly showcase the API service providers who are doing it right--this round, its the folks over at APImetrics.

The screen that comes up, when you go to add new API calls to the monitoring service is exactly what I am talking about, allowing me to get up and running using the API definition format of my choosing.

I am given the option to manually add an API, or do a bulk import of the APIs I wish to monitor using the service. I'm given the option of importing WSDL, OpenAPI Spec, RAML, Blueprint, and Postman, which reflects the leading API definition formats, any API service provider should be speaking by default. If you need help enabling this in your services, I recommend talking to the APIMATIC folks about using their API Transformer.

API definitions are quickly becoming the central contract that gets passed around among technical folks, and increasingly with business units as well. No matter where you exist on the API life cycle, between API design, all the way to deprecation, your customers should be able to onboard, and offboard using all of the modern API definition formats--enabling your users get up and running in seconds, rather than minutes, hours, or even not at all. 


Scraping Static Docs Is Often Better Than Proxy For Generating Machine Readable API Definitions

I was looking to create an APIs.json plus OpenAPI Spec(s) for the WordPress.org API, and the Instructure Canvas Learning Management System (LMS) API. I am pulling together a toolkit to support a workshop at Davidson College in North Carolina this month, and I wanted a handful of APIs that would be relevant to students, and faculty on campus

In my experience, when it comes to documenting large APIs using OpenAPI Spec, you don't want to be hand rolling things, making auto generation essential. There are two options for accomplishing this, 1) I can use a proxy like Charles or Stoplight.io, or 2) I can write a script to scrape the publicly available HTML documentation for each API. While I do enjoy playing with mapping out APIs in Stoplight.io, allowing it do the heavy lifting of crafting each API definition, sometimes there is more relevant meta data for the API available in the API documentation.

The OpenAPI Spec, plus APIs.json files for both the WordPress and Instructure Canvas APIs took me about an hour a each, to write the script, and round off the OpenAPI Spec, making sure it was as complete as possible. Through scraping, I get description for endpoints, parameters, and sometimes I also get other detail including sample responses, enum, and response codes.

One downside of obtaining an API definition by scraping, is that I only get the surface area of an API, not the responses, and underlying data model. Sometimes this is included in documentation, but I do not always harvest this--waiting until I can get a often more correct schema, when I map out using a proxy or via HAR file. This is OK. I find the trade-off worth it. I'd rather have the more human-centered descriptions, and names of each endpoints, than the response definitions--that will come with time, and more usage of the actual APIs.

In the end, it really depends to the size of an API, and the quality of the API documentation. If it is a big API, and the documentation is well crafted, it is preferable to scrape and auto generate the definition. Once I have this, I can load it into Postman or Stoplight.io, start making API calls, and use either Stoplight's proxy, or my own solution that uses Charles Proxy, to provide the remaining schema of the responses, as well as the resulting HTTP status code(s).

I think the human touch on all APIs.json, OpenAPI Spec, and API Blueprint files will prove to be essential in streamlining interactions at every stop along the API life cycle. If you can't easily understand what an API does, and what the moving parts are, the rest won't matter, so having simple, well written titles, and descriptions for APIs that are described in each machine readable definition is well worth any extra work. Even with auto generation via scraping, or Stoplight.io, I find I still have have to give each API definitions a little extra love to make sure they are as polished as possible.

I'm thinking I will start keeping a journal of the work goes into crafting each API's definition(s). It might be something I can use down the road to further streamline the creation, and maintenance of my API definitions, and the API services I develop to support all of this.

Here is the APIs.json for the Wordpress.org API by the way:

Here is the APIs.json for the Instructure Canvas API as well:

You can see these, and some other API definitions for my workshop over at the Github repo for the project. I created a new Liquid template, that allows me to display APIs.json and OpenAPI Specs within the Jekyll site for this project. Something that I will be using to better deliver API driven content, visualizations, and other resources that help us learn about, and put APIs to work.


API Definitions Are The Contract For Doing Business With APIs

I held a hangout with API Evangelist this morning, with Steve Willmot () of , & Jakub Nesetril () of  today, where we discussed API definitions. Both Steve and Jakub are CEOs of leading tech companies, who are taking frontline positions when it comes to the whole API definition conversation.

My role in this hangout, was just bringing together these two API leaders, to discuss the most important topic facing us in the world of APIs. API definitions are touching on every aspect of the API life cycle, and as Steve and Jakub discuss, playing a central role in their businesses, and their customer's businesses. We published the hour and half conversation on Youtube, so you can join in, even if you couldn't make the hangout.

 

 

The focus on API definitions being the contract, was the most important part of today's hangout for me. This wasn't a conversation about just Swagger, or API Blueprint, it was a discussion about the role API definitions play in the API life cycle, from the latest wave of API description formats like Swagger and Blueprint, to API discovery formats like APIs.json, and even media types, and schemas. These are the contracts we are using to communicate our ideas, generate code, setup tests, drive documentation, and make the API economy go roudn.

This hangout was scheduled to be an hour, but there was so much to cover, we took it an extra 30 minutes. The conversation left me feeling like I need to do this more often, expanding on the API definition discussion, but also push into other important areas like API deployment, virtualization, discovery, monitoring, and the other almost 40 areas of the API lifecycle I track on. We'll see how much time i have to do these, but more importantly my ability to bring smart people like Steve and Jakub together--something I hope I can make it work.

Thanks to Jakub and Steve for participating today!


Join @3Scale, @Apiary, And I For A Hangout On API Definitions This Wednesday

Join me, Steve Willmott(@njyx) of 3Scale, and Jakub Nesetril(@jakubnesetril) of Apiary, for a hangout on API definitions this week. I wanted to explore  doing more hangouts under the APIStrat, as well as API Evangelist brand(s)--for this one I wanted to bring together some experts to talk about the fast moving world of API definitions, as a Hangout with API Evangelist.

This Wednesday, January 27th, at 11:00 AM PST, the three of us will jump on a Google Hangout, and you are welcome to join in the conversation. We will be doing the gathering as a Hangout on Air, so that you can ask questions if you want, joining in the live conversation, or you can wait until after we are done, I will make sure and publish the video to Youtube.

Its a pretty important time for API definitions with the Swagger specification reborn as the OpenAPISpec, and Apiary, the creator of API Blueprint and MSON, also adopting OpenAPI Spec this last week, allowing you to design and mock your API in both formats. 3Scale was an earlier adopter of Swagger, and has taken a leadership position in shepherding it to into the Linux Foundation, and is a member of the governance working group.

I figured that it is a pretty good time to check-in with Steve and Jakub, on the current state of API definitions, and how they see them impacting their own platforms, as well as the overall API space. If you have any specific questions you'd like me to ask, or have any specific topics you'd like to see discussed, feel free to tweet at me. I'll tweet out the link for the event, but all you need to do is visit hangoutwith.apievangelist.com, this Wednesday at 11:00 PST, and join in the conversation.


Join Me For A Hangout With @3Scale @Apiary To Discuss Current State of API Definitions

It is an important time for API definitions. I've seen a significant uptick in the usage across the leading API definition formats, and we experienced the evolution of Swagger into the Linux Foundation, being reborn as the OpenAPI Spec. In 2016, 


An APIStrat Hangout On API Definitions With @3Scale and @Apiary


API Stack, APIs.io, And APIs.Guru Need You To Create And Share Your API Definitions

I feel pretty strongly that for the next wave of growth in the API sector, we need the majority of public APIs in use today, to have well crafted, as complete as possible, API definitions in either OpenAPI Spec or API Blueprint. Yes I know, we actually need all of these APIs to be crafted using hypermedia approaches, but until then we need them all to possess machine readable API definitions, making them discoverable, learnable, and consumable.

It is easy to get hung up on this being about API discovery, but API definitions are enabling almost every step along the 35 areas of the API life cycle I am mapping out. Historically API definitions have bee used for interactive API documentation, but more recently are additionally being used to light up other aspects of API integration, such as setting up your API monitoring, loading into the API client of your choosing, or lighting up a mock server for use in development. 

In addition enabling services and tooling throughout the life cycle, well crafted, complete API definitions is driving API design literacy. Many API developers and architects learn by reverse engineering the APIs they know, and a well crafted OpenAPI Spec or API Blueprint provides a detail blueprint for enabling this experience. API definitions make it easier to learn about good, and bad API design, in terms of the APIs you actually care about--equaling a much more open mind.

I've been working to define API definitions as part of my API Stack work, for over a year now. You can access all the APIs.json + OpenAPI Specs + API Blueprint + Postman collections under the /data folder for the project repository. Additionally, this repo is one of the sources of APIs.io which is an APIs.json driven open source API search engine, which provides an API for you to register and search for API definitions.

In 2015, I saw another strong player emerge, that I'm big on supporting--APIs.guru. The open source API definitions repository is looking to be the Wikipedia of API definitions, providing a single place we can find, robust, complete, API definitions in a variety of formats. They have done a lot of work to seed the repository with 196 APIs, possessing over 4000 endpoints, but they are looking to take things to the next level, and will need our help to this Wikipedia of APIs become a reality.

The API Stack, APIs.io, and APIs.guru all need you to help contribute, and refine the API definitions in their indexes. Developers around the world are using these definitions in their work, and modern API tooling and service providers are using them to define the value they bring to the table. To help the API sector reach the next level, we need you to step up and share the API definitions you have with API Stack, APIs.io, or APIs.guru, and if you have the time and skills, we could use your help crafting other new API definitions for popular services available today. 

If you need help getting in touch with APIs.io or APIs.guru, there is contact information on both their sites. Alternatively, feel free to just ping me with the URL of your own Github repository, and I'll make sure your API definition index gets in sync with all of this new wave of open API repositories.


Sharing 235K API Definitions With The English Language API Recipe Book

I needed a side project to reboot my mind after @APIStrat this last weekend, so I opened up my notebook and picked a project that I've been meaning to give some attention to, one that would help me clean my slate, and let me get back to my regular work levels. The project I picked is one that I came up with a little over a year ago, but recently had flushed out my vision further, as I hung out at my favorite watering whole drinking an IPA.

It took me several iterations before I landed on a name for this project, but my working title is the English Language API Recipe Book. I find myself in an awkward position these days, when it comes to the concept of API copyright, which is something I have taken a firm stance on with my work around the Oracle v Google ava API copyright case, and the release of the API licensing format API Commons, but is something, in the end, I just do not believe in.

You see, in my opinion, API definitions should NOT fall under copyright. Like recipes and menus, API definitions should not be open for anyone to use. To help me make my point, I wanted to craft the English Language API Recipe Book, publishing an open API definition for almost every word in the English dictionary. I found a reasonably complete list of every English word, and auto-generated an Open API Definition Format (OADF) specification for each of the 235K+ words. 

For each API definition, I cover the base GET, POST, PUT, and DELETE verbs for each word, providing a basic query via a parameter, and return a name, and description as the basic underlying data model. I am already playing with other variations of database models, and have also generated another dimension for each word, by again iterating through each word, and adding it as a secondary level resource. I am also playing with other relationships, and ideas for expanding the dimensions of this recipe book, but wanted to get this first version out the door.

Overall, I just want to show how easy it is to programmatically generate API definitions, and add this English Language API Recipe Book to my already growing number of API definitions, from popular APIs that I include in the API Stack. Through this work, I wanted to emphasize, that no matter how much work you put into the naming, ordering, and design of your API definitions, they are not creative works that you should lock up and defend--your API definitions should be open, easily accessible, shared, and designed for reuse.

While I do not think any of the 235K+ API definitions should have copyright applied, I will putting all of these into public domain, using a Creative Commons license, as act two of this production. This is more theater than anything, but using API Commons, I will make sure every word in the English dictionary, crafted as a basic web API, is available for anyone to use, anytime, anywhere (as it should be, DUH). I recently stated in a keynote, after launching API Commons, that I was going to be the "Johnny Fucking Appleseed" of publishing openly licensed API definitions, out in front of slower moving corporations like Oracle--the English Language API Recipe Book is just the beginning of this.

Next up, I will be crafting a series of OADF API definitions for Schema.org and use APIs.json to bundles as a more meaningful collection. I will be using these data models to further automate the English Language API Recipe Book, and establish additional dimensions to this collection. You can find the English Language API Recipe Book on Github. I have published as a Github organization, with a separate sharded repository for each letter of the alphabet, containing a separate OADF definition for each word in the dictionary, and indexed using APIs.json to index each letter, as well as for the overall recipe book collection--making it all machine readable by default.


API Visualization Exploration Using API Definitions

There are number of areas across the API life-cycle that are being expanded upon in the current space, thanks to the evolution of API definition formats like Swagger, API Blueprint, and RAML. One area I haven't seen as much growth as I'd like, is in the area of visualizations driven by API definitions

There are two distinct pools of API definition driven visualization: 1) Letting you visualize the surface area of an API 2) Letting you visualize the resource made available via an API. One area my friend the @APIHandyman has been exploring is around the surface area of API.

@APIHandyman has a nice prototype created that he is calling "Swagger Specification Visual Documentation". The API Definition driven visualization uses A D3.js visualization to help you explore the surface area of any API that is defined using Swagger. I have written about API definition driven visualizations before, so I am happy to see the concept being pushed forward, as we have a lot of iterations to cycle through before we find a visualization format(s) that works for different API designers, architects, and developers.

The visual documentation that @APIHandyman created runs on Github, and he is looking for feedback on the micro tool, and where he should take it next. He recently added a bigger information display area, but could use the communities ideas on how to make it more useful. This type of work is a time drain. Every time I started playing with Swagger + D3.js I would lose an entire evening, and have very little to show for work, so I know how valuable feedback can be.

I strongly feel that API definition driven D3.js visualizations will be the future of API design, management, and orchestration. APIs are going to continue to grow in number, and scope, and we will need simple, visual ways we can quickly traverse the landscape, and makes sense of things. If you are working on an API definition driven visualization tool, either for the surface area of an API, or helping visualize the actual resources being served up, please let me know so I can showcase.


API Definitions Broker Critical Conversations Between Business And Developers Who Are Building NextGen Web, Mobile, and Device Apps

If you are in an industry being impacted by technology, you have probably become very aware of the term Application Programming Interfaces, more widely known as APIs, and how they are driving web applications, mobile applications, and increasingly everyday objects in our homes, cars, businesses, and across the public landscape. If you are finding yourself part of this growing conversations, you have most likely have also heard talk of a new breed of API definition formats that are becoming ubiquitous like Swagger and API Blueprint.

API definitions are a way to describe what an API does, providing a machine readable blueprint of how to put the digital resource to work. API definitions are not new, but this latest round of available formats are taking the API conversation out of just IT and developer groups, and enabling business units, and other key stakeholders to participate throughout the API life-cycle. Much like the latest wave of web APIs has made data, content, and other digital resources like video and images more accessible, API definitions are making APIs more accessible across the rapidly expanding digital business landscape.

The first widely available API definition format was the Web Services Description Language (WSDL), which is an XML format established in 2001 that described web services. Much like web services (an API predecessor), WSDL was a very technical vision of APIs, something dictated by IT, and developer groups, with heavy top down governance from business and industry leadership. While web services, and WSDL are still ubiquitous across the enterprise, they are rapidly being replaced with much lighter weight, simpler web APIs that use the Internet as a way of delivering the digital data, content, and resources web, mobile, and devices are demanding in 2015.

Along the way, newer, more web friendly API definition formats emerged, such as Web Application Description Language (WADL), but ultimately WADL was something that never took root, suffering from many of the same illness of its predecessor WSDL. It wasn't until a new format called Swagger was born, that we started to see the conversation around how we define, communicate and develop standardized tooling around APIs evolve, providing an open specification for defining all the details that go into an API. 

Swagger provided developers a way to describe an API that was more in sync with everything else modern API developers were used to, including using JSON, rather than the XML of previous web services, WSDL and WADL. Swagger gave us something more than just way to define APIs, it gave us swagger UI, which is a interactive version of API documentation that made learning about what an API does, and how to integrate with it, a hands on, interactive experience. This new approach to documentation gave us a solution to the number one problem plaguing API providers, which was out of date documentation that confused consumers.

Shortly after Swagger began seeing wide adoption because of the interactive documentation it provided for APIs, a new API definition format also emerged called API Blueprint, which provided interactive documentation, but rather than using JSON, it used Markdown, making the process of defining APIs a little less intimidating for non-developers. Apiary, the makers of API Blueprint did another thing that would move the conversation forward again, making the reasons for defining APIs in these formats, more about API design, than just about delivering up-to-date documentation.

Using API Blueprint, API designers could define an API, before any code was actually written. Developers could craft an API using Apiary's tooling, then a mock version of an API could be generated, which could be shared with other project stakeholders, from business users, to potential web or mobile developers. This process saves considerable time, money, and other resources in ensuring than API would be something web, mobile, and device developers could actually put to use. With two new API definition formats Swagger, and now API Blueprint, the processing of defining, designing APIs in a machine readable way, was accessible to everyone, across a rapidly expanding API life-cycle.

This evolution has all occurred over the last 4 years, a period which has also produced other API definition formats like RSDL, RADL, RAML, I/O Docs, and MSON--just to name a few. All of these API definition formats are quickly becoming the preferred format for not just defining, and designing APIs, as well as delivering documentation. Another positive by-product has been that a new breed of API service providers are also using it as the central definition for quickly putting their services to work on any API, for documentation, mocking and virtualizing APIs, generating server code, producing software development kits (SDK), and setting up essential testing and monitoring to keep APIs stable and reliable for consumers--the API definition driven life-cycle continues to expand.

In 15 years, like APIs, the API definition formats have moved out of the real of the technical, and are providing vital business interactions that ensure APIs meet critical internal, partner, and public needs. They are also being applied to bring much needed balance to the political side of API operations, from making sure APIs are stable, and available, to defining pricing, rate limits, terms of service, and even helping secure APIs that operate on the open Internet.

API definitions have become a machine readable contract that defines the boundaries of a relationship between API provider, and its consumers. Acting as a central truth, that is crafted by developers and API architects to govern how an API operates, from mocking to client integration, but in a way that is also setting the technical, business, and legal expectations of consumers. This API definition-driven contact is transcending the often proprietary, black box algorithms that make an API function behind the scenes, providing a portable, shareable, machine readable contract that can be shared internally, and externally with partners or the general public.

The importance of this new layer, and its role in the future of software development can be seen playing out in the Oracle v Google API copyright case, where Oracle (using the courts) has set the precedent that the naming, and ordering of your interface is separate from the code, and falls under copyright protection. Beyond the core legal case, the questions, and understanding of exactly what is code has been even more interesting. Many API architects do not see APIs as anything but code, having not seen impacts of the modern API definition movement within their architecture yet.

API definitions aren't just about defining the URLs, parameters, headers, and other aspects of API operations that developers need to know, it is also bringing much needed clarity and awareness of value generated by APIs among business users, and the end-users of the applications that APIs are powering. API definitions provide a common format in markdown, YAML, or JSON, that describe the technical surface of an API, but then also take this technical specification, and allow it to be applied across every stop along the API life-cycle, from idea to deployment, to resulting integration with web, mobile, and device applications.

As APIs make their way into almost every aspect of our business and personal lives, driving our social relationships with family and friends, meter our connections to our utility companies, connect us to educational and healthcare opportunities, this touch-point between platform, and the web, mobile, and device applications it powers, is becoming increasingly critical. To businesses this layer represents critical supply chains, but to each individual this touch point is where all of our life bits flow--further emphasizing the importance of, but also the sensitivity required in defining APIs in a meaningful way, that makes sense to EVERYONE involved.

In 2001, a WSDL definition was very much about communicating what a service did between platform and an the system that was integrated, something that only involved IT, and developers. In 2015, a modern API definition format provides the same benefits that WSDL has historically delivered, but it is also addressing the business, and political elements of how Internet enabled software works.  A modern API definition provides:

  • a medium for API designs, architects, and business stakeholders to craft exactly the API that is needed, before any production code is written.
  • a necessary set of instructions needed for a quality assurance (QA) team to make sure an API meets business requirements
  • a definition of sandbox, mocking, simulation, and virtualization environments that developers may need to be successful
  • what a developer needs to integrate with another system, or build an application through interactive documentation, and even complete Software Development Kits (SDK)
  • what the API testing, monitoring, and performance groups will need to ensure service level agreements are met or exceeded
  • the known surface area that security auditor will need to properly secure the infrastructure web, mobile, devices, and ultimately users will depend on
  • a map that government regulators can use to understand the industry landscape, and help keep all players in alignment with the nations priorities

This is just a sampling of how API definitions are being used as a driver for what is widely being called the API economy, which is the heart of cloud, mobile, big data, Internet of Things (IoT), and almost every other technical trend of the last ten years. While API definitions provide the much needed machine readable instructions for computers to understand what occurs at these vital API touch-points, they also provide the much needed human readable instructions, that people can use to interpret business agreements, individual relationships, that are playing out across our increasingly digital lives.


InfoWorld - API Definitions

If you are in an industry being impacted by technology, you have probably become very aware of the term Application Programming Interfaces, more widely known as APIs, and how they are driving web applications, mobile applications, and increasingly everyday objects in our homes, cars, businesses, and across the public landscape. If you are finding yourself part of this growing conversations, you have most likely have also heard talk of a new breed of API definition formats that are becoming ubiquitous like Swagger and API Blueprint.

API definitions are a way to describe what an API does, providing a machine readable blueprint of how to put the digital resource to work. API definitions are not new, but this latest round of available formats are taking the API conversation out of just IT and developer groups, and enabling business units, and other key stakeholders to participate throughout the API life-cycle. Much like the latest wave of web APIs has made data, content, and other digital resources like video and images more accessible, API definitions are making APIs more accessible across the rapidly expanding digital business landscape.

The first widely available API definition format was the Web Services Description Language (WSDL), which is an XML format established in 2001 that described web services. Much like web services (an API predecessor), WSDL was a very technical vision of APIs, something dictated by IT, and developer groups, with heavy top down governance from business and industry leadership. While web services, and WSDL are still ubiquitous across the enterprise, they are rapidly being replaced with much lighter weight, simpler web APIs that use the Internet as a way of delivering the digital data, content, and resources web, mobile, and devices are demanding in 2015.

Along the way, newer, more web friendly API definition formats emerged, such as Web Application Description Language (WADL), but ultimately WADL was something that never took root, suffering from many of the same illness of its predecessor WSDL. It wasn't until a new format called Swagger was born, that we started to see the conversation around how we define, communicate and develop standardized tooling around APIs evolve, providing an open specification for defining all the details that go into an API. 

Swagger provided developers a way to describe an API that was more in sync with everything else modern API developers were used to, including using JSON, rather than the XML of previous web services, WSDL and WADL. Swagger gave us something more than just way to define APIs, it gave us swagger UI, which is a interactive version of API documentation that made learning about what an API does, and how to integrate with it, a hands on, interactive experience. This new approach to documentation gave us a solution to the number one problem plaguing API providers, which was out of date documentation that confused consumers.

Shortly after Swagger began seeing wide adoption because of the interactive documentation it provided for APIs, a new API definition format also emerged called API Blueprint, which provided interactive documentation, but rather than using JSON, it used Markdown, making the process of defining APIs a little less intimidating for non-developers. Apiary, the makers of API Blueprint did another thing that would move the conversation forward again, making the reasons for defining APIs in these formats, more about API design, than just about delivering up-to-date documentation.

Using API Blueprint, API designers could define an API, before any code was actually written. Developers could craft an API using Apiary's tooling, then a mock version of an API could be generated, which could be shared with other project stakeholders, from business users, to potential web or mobile developers. This process saves considerable time, money, and other resources in ensuring than API would be something web, mobile, and device developers could actually put to use. With two new API definition formats Swagger, and now API Blueprint, the processing of defining, designing APIs in a machine readable way, was accessible to everyone, across a rapidly expanding API life-cycle.

This evolution has all occurred over the last 4 years, a period which has also produced other API definition formats like RSDL, RADL, RAML, I/O Docs, and MSON--just to name a few. All of these API definition formats are quickly becoming the preferred format for not just defining, and designing APIs, as well as delivering documentation. Another positive by-product has been that a new breed of API service providers are also using it as the central definition for quickly putting their services to work on any API, for documentation, mocking and virtualizing APIs, generating server code, producing software development kits (SDK), and setting up essential testing and monitoring to keep APIs stable and reliable for consumers--the API definition driven life-cycle continues to expand.

In 15 years, like APIs, the API definition formats have moved out of the real of the technical, and are providing vital business interactions that ensure APIs meet critical internal, partner, and public needs. They are also being applied to bring much needed balance to the political side of API operations, from making sure APIs are stable, and available, to defining pricing, rate limits, terms of service, and even helping secure APIs that operate on the open Internet.

API definitions have become a machine readable contract that defines the boundaries of a relationship between API provider, and its consumers. Acting as a central truth, that is crafted by developers and API architects to govern how an API operates, from mocking to client integration, but in a way that is also setting the technical, business, and legal expectations of consumers. This API definition-driven contact is transcending the often proprietary, black box algorithms that make an API function behind the scenes, providing a portable, shareable, machine readable contract that can be shared internally, and externally with partners or the general public.

The importance of this new layer, and its role in the future of software development can be seen playing out in the Oracle v Google API copyright case, where Oracle (using the courts) has set the precedent that the naming, and ordering of your interface is separate from the code, and falls under copyright protection. Beyond the core legal case, the questions, and understanding of exactly what is code has been even more interesting. Many API architects do not see APIs as anything but code, having not seen impacts of the modern API definition movement within their architecture yet.

API definitions aren't just about defining the URLs, parameters, headers, and other aspects of API operations that developers need to know, it is also bringing much needed clarity and awareness of value generated by APIs among business users, and the end-users of the applications that APIs are powering. API definitions provide a common format in markdown, YAML, or JSON, that describe the technical surface of an API, but then also take this technical specification, and allow it to be applied across every stop along the API life-cycle, from idea to deployment, to resulting integration with web, mobile, and device applications.

As APIs make their way into almost every aspect of our business and personal lives, driving our social relationships with family and friends, meter our connections to our utility companies, connect us to educational and healthcare opportunities, this touch-point between platform, and the web, mobile, and device applications it powers, is becoming increasingly critical. To businesses this layer represents critical supply chains, but to each individual this touch point is where all of our life bits flow--further emphasizing the importance of, but also the sensitivity required in defining APIs in a meaningful way, that makes sense to EVERYONE involved.

In 2001, a WSDL definition was very much about communicating what a service did between platform and an the system that was integrated, something that only involved IT, and developers. In 2015, a modern API definition format provides the same benefits that WSDL has historically delivered, but it is also addressing the business, and political elements of how Internet enabled software works.  A modern API definition provides:

  • a medium for API designs, architects, and business stakeholders to craft exactly the API that is needed, before any production code is written.
  • a necessary set of instructions needed for a quality assurance (QA) team to make sure an API meets business requirements
  • a definition of sandbox, mocking, simulation, and virtualization environments that developers may need to be successful
  • what a developer needs to integrate with another system, or build an application through interactive documentation, and even complete Software Development Kits (SDK)
  • what the API testing, monitoring, and performance groups will need to ensure service level agreements are met or exceeded
  • the known surface area that security auditor will need to properly secure the infrastructure web, mobile, devices, and ultimately users will depend on
  • a map that government regulators can use to understand the industry landscape, and help keep all players in alignment with the nations priorities

This is just a sampling of how API definitions are being used as a driver for what is widely being called the API economy, which is the heart of cloud, mobile, big data, Internet of Things (IoT), and almost every other technical trend of the last ten years. While API definitions provide the much needed machine readable instructions for computers to understand what occurs at these vital API touch-points, they also provide the much needed human readable instructions, that people can use to interpret business agreements, individual relationships, that are playing out across our increasingly digital lives.


Please Do Not Hide Your API Definitions From Consumers

I am always pleased to see API providers publishing Swagger definitions, and using them to drive their interactive documentation. Projects like the Global Change Information System API, are getting on the API definition bandwagon, and this is a good thing. I have been pushing API definition formats like Swagger and API Blueprint since 2012, but in 2015, while I want to keep on-boarding folks to the concept of using API definitions for interactive documentation, but I also want them to also understand that their APIs definition will be used in other areas of API operations as well.

Most people think Swagger is the documentation, and have not been able able to separate the specification from the interactive documentation. I think Apiary has done a better job of this separation with the separation of API Blueprint from Apiary. As an API provider, you may not have evolved to a full API-first level of operation, which is ok, but I encourage you to make your Swagger or API Blueprint definition as accessible as possible, so your API consumers can put to use in other ways--even if you don't have the time.

As soon as I saw that the Global Change Information System API employed Swagger for their documentation, the next thing I wanted to do was also use in my Postman client. While the Swagger UI provides me with a hands-on way of getting to know the GCIS API, I have to come back to the site to play with more, and it doesn't give me as much detail about how the API works, as my Postman client does. All GCIS API team has to do, is publish a text or image link to their Swagger definition in a prominent location, so it is obvious to us consumers.

I get easily reverse engineer the Swagger UI, using my Google Developer tools, but it is a couple of extra steps for me, that stands in between me, and making calls to the GCIS API in my local Postman Client. Interactive API documentation via Swagger and Apiary has significantly moved the API definition conversation forward, but just like we should be thinking beyond just language specific clients, we also need to be enabling our API consumers to speak the formats popular HTTP clients like Postman speak.


The Swagger Definitions Collection Is The Cherry On Top Of Each API That I Profile

I create a lot of machine readable API definitions for the 1000 companies I monitor as part of my API Stack. I am using Swagger to define all of my APIs, providing me with a simple, yet powerful way to profile each of the APIs I'm working to understand better. If you aren't familiar with Swagger, it provides a handful of fields you can use to fill out the metadata profile for APIs, like title, description, etc., but where it really gets powerful is when you put the paths collection to work, outline the details of each endpoint.

Most of the APIs I come across that are defined using Swagger, focuses on providing details on each path, including verbs, headers, parameters, and sometimes response status codes. When looking for the benefits of Swagger, many stop here. With basic metadata, and details about the paths, you can launch interactive documentation using Swagger UI--which is how about 80% of folks are using the API specification format.

When it comes to Swagger, my own motivations are all about API discovery, so when crafting Swagger files for the APIs I track on, I can easily call it quits after defining the basic meta information, and path details, but all of this ignores some of the exremely valuable aspect of using Swagger--with the definitions collection.

Using the Swagger definitions collection you can quantify the underlying data model across API operations, providing a machine readable profile of the XML and JSON that will be part of each API request and response. Once you have the underlying data model defined, including each parameter, description, and type, you can then link to each path and / or parameter, where the data model is being put to use as part of the request or response. 

Swagger definition collections are not a requirement for Swagger UI, or for API discovery currently, but if you want to generate high quality server side code, or client SDKs, you will need a complete set of definitions present. The problem is, this is a shitload of work, and as I face the Swagger definition for Twitter, I'm looking at many hours of work if I want to ensure that Twitter's Swagger file has all of its underlying data model present, understanding why many people stop short of a complete Swagger spec.

In the end, the Swagger definition collections is really the cherry on top of each API I am profiling, highlighting the maturity of a particular API definition, demonstrating that you can do more with a machine readable definition, than just discovery, and documentation.


Parsing Charles Proxy Exports To Generate Swagger Definitions, While Also Linking Them To Each Path

Making sure the Swagger files I craft possess a complete definition for its underlying data model, one that is linked to each API path, and parameters where it is put to use, is important to me, but damn it is a lot of work. As I mentioned in my last piece I'm looking at the Twitter Swagger file, and my head starts spinning thinking about how much work it will be to hand-define all of the data models that used across the almost 100 Twitter endpoints.

I quickly got to work finding a better solution--I landed on Charles Proxy. I had downloaded and installed Charles Proxy to better understand how we could map out the dark layer of the API universe, that the popular mobile applications we use depend on. When running, Charles proxies all the requests and responses my desktop apps, and browsers make on my local Macbook. I can also route my iPhone and iPad through the proxy, when I want to also record my mobile app usage. This is perfect for helping me map out the public APIs in my API Stack work!

When the Charles Proxy is running, it saves an XML summary export to my local Dropbox folder, which then gets synced to the cloud via the Dropbox API. I am now working on a script that will keep an eye on my Dropbox folder, and process any new Charles export files it finds. As I process each file, I'm cherry picking from the domains of specific companies that I'm tracking on, pulling out the request and response information I need to craft a Swagger definition. 

To generate the traffic I need, I just load up any API I'm looking to profile in Postman, and started working my way through the list of endpoints, until I've covered the entire surface area of any API. I find it is easy to generate a beginning Swagger definition, which includes the host, base uRL, endpoints, and parameters, then load it into Postman, and let Charles proxy complete the rest of the Swagger definition collection, and link each one to any path or parameter it is referenced by. I will be running checks on request details, to make sure I haven't forgotten about any endpoints, and parameters, but my goal is primarily around polishing the definition collection, with an endpoint linkage.

I will not rely on these Swagger definitions generated from the Charles proxy. I will be queuing them up in a Github repo(s), and syncing them existing, often hand-crafted Swagger definitions I'm already evolving. Hopefully this process will help me automate the profiling of popular public APIs, and enable me to crank through more APIs this summer, as part of my API Stack research.

All of this is working out well. My need to automate the defining of underlying data models, reminded me of the dark API work I was already doing with Charles Proxy--something I will spend more time on this summer. I am looking to generate a Swagger definition for each of the desktop apps I use on my MacBook, and the mobile apps I use on my iDevices--stay tuned!


Using API Definitions To Help API Providers With Their API Design Roadmap

As I work to create Swagger API definitions for the almost 1000 companies in my API stack, I'm chasing an elusive definition of a complete Swagger definition for any API. Only a small portion of APIs I am defining using Swagger will reach an 80-90% completions status, in reality most will never be complete for reasons that are totally out of my control.

When it comes to crafting API definitions for public APIs, I may be able to get the API definition complete in the sense that it has all the paths, parameters, responses, definitions, and security configurations, but if the API itself is missing pieces--the API definition will always be incomplete (in perpetuity).

As I work to automate the questions I ask of Swagger definitions, helping me get to a more coherent definition of what is a complete Swagger definition, I can't help feel the need to offer API design tips to the API providers I am profiling. Honestly I have never considered myself a high quality API designer, I've been more business than tech, but I can't help pointing out the obvious stuff. 

I am still using my API definition tooling for my own goals around defining the API Stack, but because I'm building it all as APIs, I intend to open it up to others for analyzing their own API definitions, determining how complete they are, and potentially offering up tips on what could be done to improve them. A kind of self-service, API design tip API, that helps with some of the most common elements that are missing from API designs.

In 2015, API definitions are opening up a buffet of services that are courting API providers ranging from mocking and deployment, to monitoring and security. I don't see why API definitions couldn't also allow for professional API designers to help API providers evolve their APIs in a more constructive ways, from the outside-in. Using Swagger or API Blueprint, professional designers could easily provide suggestions for existing API providers and their designs, then give them potential suggestions that they could use in their API design road-map.

Anyhoo, food for thought!