API Evangelist
API Evangelist is about making sense of the world of application programming interfaces, or simple APIs. APIs have become part of every layer of our Internet connected world over the last 20 years, and this is my research project into understanding what is happening. As of 2019 I am also the Chief Evangelist for Postman, but I still use this site in the same way I have since 2010, as a workbench for what I am working on each day. Providing me with a very public way to work through my projects, while helping others see the world of APIs in different ways, and hopefully learn more about how APIs are being applied across our world
This isn't meant to be a blog in the traditional sense of the word, and you should think of it as Kin Lane's personal notebook that he is fine with others reading. Once you spend time reading my work you will better understand that this is my souning board, helping me work through my ideas, and I am not doing this for page views, audience size, or other metric. However, after over ten years of doing this I tend to have a regular group of folks who are tuning in and providing commentary via Twitter, GitHub, and other channels.
Latest Posts
My Oracle vs Google API Copyright Journey
13 Apr 2021
Soon after beginning my journey as the API Evangelist in 2010 I began quickly realizing that there was more to this game than just technology. The mission of the blog was to get beyond the technology of APIs, and focus on the business of APIs. Which in 2010 was emerging as the biggest driver of why and how you do APIs, over the actual technical styles, practices, and approaches to delivering API infrastructure. I also quickly realized that it wasn’t just about business, and that there direct and indirect political layers that determine which direction APIs are pushing the tech sector. One critical conversation involving APIs that spans both the business and politics of APIs was the Oracle vs. Google copyright case. I had read about the case back in 2010 and 2011, but I really didn’t understand what it meant until the case got up and running in 2012. Kicking off an almost decade long journey for me as I studied and thought about API copyright, followed the case, then actually begin contributing to the case as part of the EFF’s push to help keep APIs free from copyright, ultimately coming to a conclusion this last week as the Supreme Court returned their decision that APIs were indeed copyrightable, but Google’s use of the Java APIs was indeed fair use. The Oracle vs. Google API copyright case began as two parts, 1) for patent violations, and 2) for copyright infringement involving the Java API. The jury found Google in violation of copyright law for the 11,500 lines of code they reused from the Java API, but acknowledged that it fell under fair use, and then found no fault in the claim of patent violations. However, in the end Judge Alsup declared that fair use didn’t apply because you can’t actually copyright APIs—-which gets at the truth of all of this in my belief. The judge went the extra mile by actually learning Java so...[Read More]
Aligning the API Specification Contribution Process Across OpenAPI, AsyncAPI, and GraphQL
02 Apr 2021
Mike Ralphson (@permittedsoc) suggested that the OAI follow AsyncAPIs lead when it comes to adopting a GraphQL like approach to managing contributions to the specification in the OpenAPI specification technical steering committee (TSC) yesterday. AsyncAPI has followed GraphQL lead as it enters the Linux foundation, and it is something that the OAS TSC is strongly considering. Here are links to the existing contribution guidelines for these three specifications: GraphQL Contribution Guidelines AsyncAPI OpenAPI Admittedly, the OAS “participation” framework is a bit of a special snowflake, which has been mentioned might be one aspect of operations that might be preventing the specification from shifting gears into its next phase of development. To help me learn more about the approach I wanted to break down the GraphQL and AsyncAPI approach. GraphQL - Guiding Principles Backwards compatibility - Once a query is written, it should always mean the same thing and return the same shaped result. Future changes should not change the meaning of existing schema or queries or in any other way cause an existing compliant GraphQL service to become non-compliant for prior versions of the spec. Performance is a feature - GraphQL typically avoids syntax or behaviors that could jeopardize runtime efficiency, or that make demands of GraphQL services which cannot efficiently be fulfilled. Favor no change - As GraphQL is implemented in over a dozen languages under the collaboration of hundreds of individuals, incorporating any change has a high cost. Accordingly, proposed changes must meet a very high bar of added value. The burden of proof is on the contributor to illustrate this value. Enable new capabilities motivated by real use cases - Every change should intend on unlocking a real and reasonable use case. Real examples are always more compelling than theoretical ones, and common scenarios are more compelling than rare ones. RFCs should do more than offer a different way to reach an already achievable outcome. Simplicity and consistency over expressiveness and terseness...[Read More]
When API Examples Become the Real Thing
31 Mar 2021
I am using Postman public workspaces to manage all of my projects right now, and as part of my Postman collection workspace I have a variety of collections where I am bending the concept of how Postman was intended to be used. I was needing many little APIs for my API specification projects to organize a mix of data I will be using to automate and orchestrate information gathering, publishing, and any other task I can automate in my world. After considering using AWS API Gateway + DynamoDB for this, I thought that it would be easier, and more cost effective for me to just use Postman. The platform doesn’t have an API deployment capability, and we do have integrations like with AWS API Gateway, but I really feel like these simple little APIs were even too small for justifying the increase on my AWS bill—I was determined to find a way to do on Postman. I knew I could accomplish what I wanted on Postman, I just needed to think out of the box a little. After some brainstorming I decided to just define each individual data store as a single collection, use the examples as the actual data store, then publish a mock server—-treating the result as more of a “static” API than a mock for testing or other purposes. I ended up with six separate static APIs that are hosted 100% on Postman. Articles (Docs) (Data) - Interesting articles that have been written about Postman Collections. Competition (Docs) (Data) - A list of example of how Postman competitors are using Postman Collections. Government (Docs) (Data) - Showing the different government agencies who are using Postman Collections. Pages (Docs) (Data) - The interesting pages that API Providers have published showcasing their collections. Partners (Docs) (Data) - Demonstrating how Postman partners are importing and exporting Postman Collections. Tooling (Docs) (Data) (Data) - All of the tooling I track on that is built around the...[Read More]
A Workspace for Defining the API Lifecycle
30 Mar 2021
I am moving my API lifecycle definition into a public workspace so that I can be a little more disciplined in how I version and move forward. It is a pretty lightweight draft at this point because I still have to coordinate internally more about Postman around it, as well as with some partners, but this first version helps me frame the discussions I am having. To help guide the process of defining the API lifecycle I created an OpenAPI to help provide the scaffolding for an API to define the API lifecycle, using Postman mocks and documentation to make things a little more tangible and real. The creation of the OpenAPI, then generation of the Postman collection and example to help act as the data store for my static API lifecycle API provides me with a nice separation of the structure of how I’d like to talk about the API lifecycle, and the actual data and content that defines the API lifecycle. Using Postman public workspaces as an incubator for defining the API lifecycle in a machine readable and collaborative way. Allowing anyone to discover and play with via the public API workspace, but also allow them to fork and contribute to the work via pull requests, and engage in the feedback loop using Postman comments on the collection or the API—-further separating the conversation around the structure and details of the API lifecycle.[Read More]
A Workspace for Defining API-First
30 Mar 2021
Alongside my API lifecycle public workspace I have established an API-first public workspace to help me guide conversations around what is API-first. Like the API lifecycle it is another area we use a lot, but don’t always have a coherent and relatable meaning behind exactly what it means. To get really meta, I am using an API-first process to define the API-first process (mind blown). I am using Postman to define an OpenAPI, which provides me with a structure and schema for how I will be defining API-first, but then I use collection examples to store the API-first definition I am evolving, then I mock and document it to make it a little more tangible, making it all available in a single API workspace. I am looking to get more precise when I talk about the API lifecycle and API-first. There is no better way to be precise than using an API defined using an API-first process. I learned a lot by setting up the OpenAPI, collections, environment, and mock server for this definition. It pushed me to think a little more deeply about what it is I am trying to define, and pushed me to separate the scaffolding and framework for the definition, from the actual details of the implementation. The API-first workspace provides me with a framework and definition for pushing me forward in this journey, but it also makes it accessible to others to join in via the public workspace, and contribute to the framework via the OpenAPI, or the actual API-first definition using the collection, allowing anyone to fork and submit pull requests, or just leave feedback via the API or collection level comments.[Read More]
A CSV to JSON File Conversion Postman Collection
29 Mar 2021
I am regularly needing to convert CSV files into JSON, and to help me manually get the job done, as well as automate on a schedule or via the Postman API, I created a simple request for pulling a CSV file and converting into a JSON response, and then rendering using the Postman Visualizer. You can view the documentation for the collection in my file format conversion public workspace. I will be adding other file format conversion requests for this collection as I need them. If you have one you’d like to add feel free to fork the collection and add it yourself! ;-) If you have any feedback, feel free to comment on the collection, or any part of requests.[Read More]
A Collection To Generate Static APIs Using Postman Mock Servers
29 Mar 2021
I have a lot of little datasets I am organizing for use across a variety of projects. Since Postman has replace Github as my place where I begin all of my API projects, I figured that it could also be used host all of my data projects as APIs. Postman collections often times resemble an OpenAPI definition in that it provides a reference of an API, but in practice collections go much further, allowing you to store example data so that it can be better used in documentation, mocks, testing, and other types of purposes. You can store examples in OpenAPI, but Postman really allows you to go the distance when it comes to actually bringing those examples to life as a documented static API using Postman collections and mock server. An example of this in action can be found with [my Fortune 500 public workspace](https://api-evangelist.postman.co/workspace/Fortune-500~08e01ed9-6906-47a0-a81e-369948912ef4/overview). I needed a list of 2020 Fortune 500 companies so that I can use it a variety of data mining and automation projects. I can easily download the data and publish a proper API, but it is so easy for me to use Postman collection in conjunction with the mock feature to publish simple mock APIs for each of my datasets. Using Postman as a sort of poor mans API hosting, which I won’t be opening up for public use, but will be using across a number of my API Projects. However, just because I won’t be sharing the URLs of my static (mock) APIs, I will be sharing all the collections I have developed around this work, beginning with my collection for generating my static (mock) data API from a CSV. This is just a first version of my collection for pulling any CSV, converting the CSV to JSON, creating a collection, adding the JSON as an example, and then publishing my collection to my public workspace. Next I will be adding an option for adding JSON converted...[Read More]
