This website is currently dormant!

API Definitions News

These are the news items I've curated in my monitoring of the API space that have some relevance to the API definition conversation and I wanted to include in my research. I'm using all of these links to better understand how the space is defining not just their APIs, but their schema, and other moving parts of their API operations.

The OpenAPI 3.0 GUI

I have been editing my OpenAPI definitions manually for some time now, as I just haven’t found a GUI editor that works well with my workflow. Swagger editor really isn’t a GUI solution, and while I enjoy services like, APIMATIC, and others, I’m very picky about what I adopt within my world. One aspect of this is that I’ve been holding out for a solution that I can run 100% on Github using Github Pages. I’ve delusionally thought that someday I would craft a slick JavaScript solution that I could run using only Github Pages, but in reality I’ve never had the time to pull together. So, I just kept manually editing my OpenAPI definitions on the desktop using Atom, and publish to Github as I needed.

Well, now I can stop being so dumb, because my friend Mike Ralphson (@permittedsoc) has created my new favorite OpenAPI GUI, that is OpenAPI 3.0 compliant by default. As Mike defines it, “OpenAPI-GUI is a GUI for creating and editing OpenAPI version 3.0.x JSON/YAML definitions. In its current form it is most useful as a tool for starting off and editing simple OpenAPI definitions. Imported OpenAPI 2.0 definitions are automatically converted to v3.0.”

He provides a pretty simple way to get up and running with OpenAPI GUI because, “OpenAPI-GUI runs entirely client-side using a number of Javascript frameworks including Vue.JS, jQuery and Bulma for CSS. To get the app up and running just browse to the live version on GitHub pages, deploy a clone to GitHub pages, deploy to Heroku using the button below, or clone the repo and point a browser at index.html or host it yourself - couldn’t be simpler.” – “You only need to npm install the Node.js modules if you wish to use the openapi-gui embedded web server (i.e. not if you are running your own web-server), otherwise they are only there for PaaS deployments.”

Portable, Forkable API Design GUI The forkability of OpenAPI GUI is what attracts me to it. The client-side JavaScript approach makes it portable and forkable, allowing it to run wherever it is needed. The ability to quickly publish using Github Pages, or other static environment, makes it attractive. I’d like to work on a one click way for deploying locally, so I could make available to remote microservices teams to use locally to manage their OpenAPI definitions. I think it is important to have local, as well as cloud-based API design GUI locations, with more investment in the cloud-base solutions being more shared, possessing a team component, as well as a governance layer. However, I really like the thought of each OpenAPI having its own default editor, and you edit the definition within the repo it is located. I could see two editions of OpenAPI GUI, the isolated edition, and a more distributed team and definition approach. IDK, just thinking out loud.

Setting the OpenAPI 3.0 Stage The next thing I love about OpenAPI GUI is that it is all about OpenAPI 3.0, which I just haven’t had the time to fully migrate to. It has the automatic conversion of OpenAPI definitions, and gives you all the GUI elements you need to manage the robust features present in 3.0 of the OpenAPI specification. I’m itching to get ALL of my API definitions migrated from 2.0 to 3.0. The modular and reusable nature of OpenAPI 3.0, enabled by OpenAPI GUI is a formula for a rich API design experience. There are a lot of features built into the expand and collapse GUI, which I could see becoming pretty useful once you get the hang of working in there. Adding, duplicating, copying, and reusing your way to a powerful, API-first way of getting things done. I like.

Bringing In The Magic With Wizards Ok, now I’m gonna go all road map on you Mike. You know you don’t have to listen to everything I ask for, but cherry pick the things that make sense. I see what you are doing in the wizard section. I like it. I want a wizard marketplace. Go all Harry Potter and shit. Create a plugin framework and schema so we can all create OpenAPI driven wizards that do amazing things, and users can plugin and remove as they desire. Require each plug to be its own repo, which can be connected and disconnected easily via the wizards tab. I’d even consider opening up the ability to link to wizards from other locations in the editor, and via the navigation. Then we are talking about paid wizards. You know, of the API validation varietal. Free validations, and then more advanced paid validations. ($$)

Branding And Navigation Customization I would love to be able name, organize, and add my own buttons. ;-) Let’s add a page that allows for managing the navigation bars, and even the icons that show within the page. I know it would be a lot of work, but a great thing to have in the road map. You could easily turn on the ability to add logo, change color palette, and some other basics that allows companies to easily brand it, and make it their space. Don’t get me wrong. It looks great now. It is clean, simple, uncluttered. I’ve just seen enough re-skinned Swagger UI and editors to know that people are going to want to mod the hell out of their GUI API design tooling. Oh yeah, what about drag and drop–I’d like to reorder by paths. ;-) Ok, I’ll shut up now.

OpenAPI GUI In A Microservices World As I said before, I like the idea of one editor == one OpenAPI. Something that can be isolated within the repo of a service. Don’t make things too complicate and busy. In my API design editor I want to be able to focus on the task at hand. I don’t want to be distracted by other services. I’d like this GUI to be the self-container editor accessible via the Jekyll, Github Pages layer for each of my microservices. Imagine a slightly altered API design experience for each service. I could have the workspace configurable and personalized for exactly what I need to deliver a specific service. I would have a base API design editor for jumpstarting a new service, but I’d like to be able to make the OpenAPI GUI fit each service like a glove, even making the About tab a README for the service, rather than for the editor–making it a microservice dashboard landing page for each one of my services.

Making API Design a Shareable Team Sport Ok, contradicting my anti-social, microservices view of things. I want the OpenAPI GUI to be a shareable team environment. Where each team member possesses their own GUI, and the world comes to them. I want a shared catalog of OpenAPI definitions. I want to be able to discover widely, and checkout or subscribe to within my OpenAPI GUI. I want all the reusable components to have a sharing layer, allowing me to share my components, work with the shared components of other developers, and work from a central repository of components. I want a discovery layer across the users, environments, components, OpenAPI definitions, and wizards. I want to be able to load my API design editor with all of the things I need to deliver consistent API design at scale. I want to be able to reuse the healthiest patterns in use across teams, and possibly lead by helping define, and refine what reusable resources are available for development, staging, and production environments.

Github, Gitlab, or BitBucket As A Backend For The OpenAPI GUI I want to run on Github, Gitlab, or BitBucket environments, as a static site–no backend. Everything backend should be an API, and added as part of the wizard plugin (aka magic) environment. I want the OpenAPI, components, and any other artifacts to live as JSON or YAML within a Github, Gitlab, or BitBucket repository. If it is an isolated deployment, everything is self-contained within a single repository. If it is a distributed deployment, then you can subscribe to shared environments, catalogs, components, and wizards via many organizations and repositories. This is the first modification I’m going to do to my version, instead of the save button saving to the vue.js store, I’m going to have it write to Github using the Github API. I’m going to add a Github OAuth icon, which will give me a token, and then just read / write to the underlying Github repository. I’m going to begin with an isolated version, but then expand to search, discovery, read and write to many different Github repositories across the organizations I operate across.

Annotation And Discussion Throughout While OpenAPI GUI is a full featured, and potentially busy environment, I’d like to be able to annotate, share, and discuss within the API design environment. I’d like to be able to create Github issues at the path level, and establish conversations about the design of an API. I’d like to be able to discuss paths, schema, tags, and security elements as individual threads. Providing a conversational layer within the GUI, but one that spans many different Github repositories, organizations, and users. Adding to the coupling with the underlying repository. Baking a conversational layer into the GUI, but also into the API design process in a way that provides a history of the design lifecycle of any particular service. Continuing to make API design a team sport, and allowing teams to work together, rather than in isolation.

API Governance Across Distributed OpenAPI GUIs With everything stored on Github, Gitlab, Bitbucket, and shareable across teams using organizations and repositories, I can envision some pretty interesting API governance possibilities. I can envision a distributed API catalog coming into focus. Indexing and aggregating all services, their definitions, and conversations aggregated across teams. You can see the seeds for this under the wizard tab with validation, visualization, and other extensions. I can see there being an API design governance framework present, where all API definitions have to meet certain number of validations before they can move forward. I can envision a whole suite of free and premium governance services present in a distributed OpenAPI GUI environment. With an underlying Github, BitBucket, and Gitlab base, and the OpenAPI GUI environment, you have the makings for some pretty sweet API governance possibilities.

Lot’s Of Potential With OpenAPI GUI I’ll pause there. I have a lot of other ideas for the API design editor. I’ve been thinking about this stuff for a long time. I’m stoked to adopt what you’ve built Mike. It’s got a lot of potential, and a nice clean start. I’ll begin to put to use immediately across my API Evangelist, API Stack, and other API consulting work. With several different deployments, I will have a lot more feedback. It’s an interesting leap forward in the API design tooling conversation, building on what is already going on with API service providers, and some of the other API design tooling like Apicurio, and publishing the API design conversation forward. I’m looking forward to baking OpenAPI GUI into operations a little more–it is lightweight, open source, and extensible enough to get me pretty excited about the possibilities.

Google And AWS APIs Available In Visual Studio And Eclipse IDEs

I'm always learning from the API pioneers, and trying to understand how they are pushing forward the API conversation. I'm neck deep in profiling AWS APIs, as well as Google APIs. One common pattern I'm seeing across both providers is the support for API access in both Visual Studio and Eclipse IDEs. 

Google is helping developers find APIs within both of the leading IDE platforms. They have long had some Eclipse plugins for their API infrastructure, but I recently noticed they also have a pretty robust solution for Visual Studio developers. The Google APIs .NET library is made available in Visual Studio using the NuGet package manager, opening up access to a significant portion of their API stack.

Amazon also provides Eclipse and Visual Studio tooling as part of their AWS toolbox. Opening up access the AWS API catalog to developers in the IDE they are are using to build their applications and craft their system integrations. I don't know how much time you've spent looking through the AWS catalog, but it can be a timesucker--giving me access to APIs in my native environment makes a lot sense.

I feel like API innovation in the IDE is right there with API integration into our continuous integration workflows, and the usage of Github. You should haven't to depend on Google to find your APIs, they should be right at your fingertips in your IDE, no matter whether they are for your applications, or for managing your API operations. All your internal, and 3rd party APIs should be baked into your development, and continuous integration environments, allowing you to orchestrate exactly the application experience, and life cycle you desire. This is just one of the fronts I'd like to see API discovery evolve in coming years, reaching developers with new APIs and paths during design and development, as well as across continuous integration stages of our work.

Azure and Office APIs in Visual Studio

I was reviewing the latest changes with Visual Studio 2017 and came across the section introducing connected services, providing a glimpse of Microsoft APIs baked into the integrated development environment (IDE). I've been pushing for more API availability in IDE's for some time now, something that is not new, with Google and SalesForce having done it for a while, but is something I haven't seen any significant movement in for a while now.

I have talked about delivering APIs in Atom using APIs.json, and have long hoped Microsoft would move forward with this in Visual Studio. All APIs should be discoverable from within any IDE, it just makes sense as a frontline for API discovery, especially when we are talking about developers. Microsoft's approach focuses on connecting developers of mobile applications, with "the first Connected Service we are providing for mobile developers enables you to connect your app to an Azure App Service backend, providing easy access to authentication, push notifications, and data storage with online/offline sync".

In the picture, you can see Office 365 APIs, but since I don't have Visual Studio I can't explore this any further. If you have any insight into these new connected services features in the IDE, please let me know your thoughts and experiences. If Microsoft was smart, all their APIs would be seamlessly integrated into Visual Studio, as well as allow developers to easily import any other API using OpenAPI, or Postman Collections. 

While I think that IDEs are still relevant to the API development life cycle I feel like maybe there is a reason IDEs haven't caught up in this area. It feels like a need that API lifecycle tooling like PostmanRestlet Client, and Stoplight are stepping up to service the area. Regardless I will keep an eye on. It seems likno-braineriner for Microsoft to make their APIs available via their own IDE products, but maybe we are headed for a different future where a new breed of tools helps us more easily integrate APIs into our applications--no code necessary.

API Discovery Continues Its Move Into The IDE With Eclipse Che

Another layer to the release of Codenvy this week, was the announcement of the Eclipse project Che, an open source "project to create a platform for SAAS developer environment that contains all of the tools, infrastructure, and processes necessary for a developer to edit, build, test, and debug an application”. Che represents the next generation IDE that runs in the cloud, which coincides with other signs I've seen around API discovery moving into the IDE with signals from API pioneers like SalesForce and Google, or from Microsoft in Visual Studio.

I’m still learning about Che, but I’m beginning to see two distinct ways Che and APIs can be employed. First lets start with the environment:

You can build extensions for Che, and when those extensions are compiled into the kernel, Che creates server-side microservices, a RESTful API, and cross-browser optimized JavaScript, which is then pluggable into a browser IDE. With Che, developers are given the pluggable structure of Eclipse, but accessible through a cloud environment.

This means you can orchestrate development workflows, with APIs. You can predefine, deploy, customize, maintain and orchestrate very modular development environment where everything can be controlled via API. What a perfect environment for orchestrating the next generation of application development.

Next I see APIs leading the development lifecycle as well, not just defining the development environment and process. Earlier stories I’ve done on API discovery via SDKs, showcase SaleForce and Google providing native discovery of their APIs directly in Eclipse. In an Eclipse Che driven development environment, you could define pre-built, or custom API stacks, bringing exactly the API resources developers will need and bake them directly into their IDE—meaning APIs find the developers, developers don’t have to find their own APIs.

This approach to API discovery via the IDE provides some various interesting opportunity for marrying with earlier thoughts I’ve had around being an API broker. I can envision a future where API evangelism evolves to a point where you don’t just represent one API, you can represent many APIs, and configure API fueled developer environments for building any type of application. Think of what Backend as a Service (BaaS) providers like Parse and Kinvey have been doing since 2011, but now think of pre-configured, or custom tailored IDE environments with exactly the resources you need.

I’m just getting started with Che, and Codenvy, so it will take me a while to work through my thoughts on using it as an API brokerage platform. The one thing you can count on me for, is that I will tell stories all along the way as I figure it out.

Disclosure: API Evangelist is an advisor to Codenvy.

Expanding The Layer Of API Discovery From Within The Developers IDE

Much like API design and integration, the world of API discovery is heating up in 2014. We are moving beyond the API directory as our primary mode of API search, in favor of a distributed approach using APIs.json, and supporting open source search engines like Another area of API discovery I’ve been watching for a while, and predict will become an important layer of API discovery, will be via the Integrated Development Environment (IDE) plugin.

Open Source SalesForce API IDE Plugin
SalesForce just announced they have just open sourced their API IDE plugin on Github, after developing on it since 2007, when APEX was born. The plugin is old, but is very much in use in the SalesForce ecosystem, something I’ve written about before. They will be accepting pull requests on the main branch, looking to improve on the codebase, while looking to also maintain a community branch, as well as encouraging you to establish your own branch.

Does Your API Have An IDE Plugin?
How far along are you on your own APIs Eclipse Plugin? Are you trying to reach enterprise developers with your API resource? You should probably look at the pros and cons of providing your API developers with a plugin, for leading IDEs. With the open sourcing of SalesForce API IDE plugin, you can reverse engineer their approach and see what you can use for your own APIs IDE plugin—smells like a good opportunity to me.

Opportunity For General Or Niche API IDE Plugins
Not that using SalesForce open source IDE would be the place to start for this kind of project, but I think there is a huge opportunity to develop API focused IDE plugins, for top developed environments, across many popular APIs. Developers shouldn’t have to leave their development environments to find the resources they need, they should be able to have quick access to the APIs they depend on te most, and discover new API resources right from their local environment, aking IDE plugins an excellent API discovery opportunity.

Native Opportunities For IDE Platforms
I’ve seen a lot of new development environments emerge, many are web-based, with varying degrees of being “integrated”. I think that IDE developers can take a lead from Backend as a Service (BaaS) providers and build in the ability to define an integrated stack of API resources, right into a developer's web, mobile, or Iot development environment. If you are building a platform for developers to produce code, you should begin baking in API discovery and integration directly into your environment.

All I do as the API Evangelist, is shed light on what API pioneers like SalesForce are up to, and expand on their ideas, using my knowledge of the industry--resulting in these stories. SalesForce has been doing APIs for 14 years now, and the IDE has been part of their API driven ecosystem for the last seven years. I think their move to open source the technology, is an opportunity for the wider API space to run with, by helping improve the community SalesForce API IDE plugin, but also apply their experience, and legacy code to help evolve and improve on this layer of API discovery, available within the IDE.

If you think there is a link I should have listed here feel free to tweet it at me, or submit as a Github issue. Even though I do this full time, I'm still a one person show, and I miss quite a bit, and depend on my network to help me know what is going on.