Skip to main content
search
All Posts By

kinlane

Jul 15
Love0

An OpenAPI Interview with Marc-André Giroux of Github

By Blog

By Kin Lane, Chief Evangelist at Postman, and Co-Chair of the OpenAPI Initiative (OAI) Business Governance Board (BGB)

I recently sat down with Marc-André Giroux, Staff Developer at GitHub about their OpenAPI journey, to learn more about how the social coding platform employs OpenAPI across the API lifecycle. GitHub plays a central role in the development of software of any kind and is also central to the entire API lifecycle, but the platform’s APIs provide a wealth of learnings when it comes to how to deliver API infrastructure scale. So we are honored to have sat down for this discussion about the OpenAPI journey GitHub is on, and share this vision with the OAS community.

When did you begin your journey using the OpenAPI specification?

GitHub began looking into OpenAPI in 2019. Funnily enough, two teams started to look at it independently, which highlights how OpenAPI brings many different benefits to the table. On one end, our documentation team wanted a machine-readable document from which to generate their documentation. On the other hand, the API team (the team I am on) wanted to use OpenAPI as something core to our API development experience. Things like having a design-first flow, request validation, contract testing, linting, etc.

Our documentation team started exploring with OpenAPI first. They ingeniously generated an initial document from our hand-written documentation. This was a great start, but from our API team’s perspective, since it was generated from something that we could not entirely trust, it was important for us that this OpenAPI description was being tested against, and used by our runtime code to make sure it is both accurate and complete.

Over the first half of 2020, we worked with the documentation team to use their initial work, bring it over to the API’s codebase and use it in a validation middleware that would tell us about any mismatches. We built tooling to automatically fix errors, fixed a lot of errors by hand, and in July 2020, we were ready enough to release the beta of our OpenAPI description.

What teams are currently using OpenAPI within your organization?

The surface area of our API  is very wide. Almost every team working on a feature at GitHub will end up writing an API for it. This means that in the end, a ton of different teams interact with OpenAPI. As the API team, we consider these teams to be our customers as well. We make sure their experience with OpenAPI is great and that we have the right tooling to help them build great APIs. Our documentation team also uses OpenAPI to generate most of our API documentation website.

Is OpenAPI used for public APIs? Internal APIs? Or Both?

OpenAPI is currently only used for our public API. We have a lot of internal APIs that we would eventually like to describe with OpenAPI. However, we’ve recently made the switch to using Twirp for most internal use cases, which is described by Protobufs.


Can you share more about how OpenAPI is being used across different areas?

Documentation:

The OpenAPI written by our developers gets automatically synced with our documentation repository. Our documentation team built an amazing pipeline which decorates the OpenAPI further and is used to render our API documentation.

Code Generation

We also sync the OpenAPI description in our open-source repository. This is used by our first use case of code generation, the Octokit JS SDK. Gregor Martynus did an amazing job using the OpenAPI we publish to generate typescript types and power the javascript SDK.

Soon, we want to help our own developers with code generation as well. We already leverage OpenAPI operations at runtime to configure certain resources, but we want to push it further and help generate implementations from OpenAPI operations.

Testing

GitHub’s API is implemented in an enormous Ruby monolith, with thousands and thousands of existing tests. We leveraged this by including a custom OpenAPI validation middleware in our existing integration testing suite for the API. This contract testing is integral to our confidence in the accuracy of our OpenAPI documents and was one of the hardest, and most important, parts of our OpenAPI work.

A lot of existing OpenAPI validators return errors that are not necessarily friendly to users. We spent a lot of time coming up with an abstraction that lets us return errors that are either developer-facing or end-user-facing. For example, the OpenAPI validation errors that are returned as part of our integration tests return error messages that instruct the developer on why the error happened and how to fix it. On the request validation side of things, we instead instruct the user on why their input was invalid, and how to correct it.

What were the driving factors for you to adopt OpenAPI?

While generating documentation was an amazing benefit, OpenAPI was more than just that to us. Enabling powerful tooling and building a great developer experience were the main reasons we looked at OpenAPI.

Do you make a copy of your OpenAPI available for download by users? If so, where do you make it available?

We do! As mentioned earlier, we have it available as an open-source repository located here.

Do you currently have any OpenAPI extensions you are using or have established as part of your operations?

We use quite a few extensions that are useful at different stages of the “lifecycle” of our operations. We support many different versions of GitHub’s REST API. Our classic public API, but also every version of GitHub enterprise. While the APIs are similar, they do have differences across versions. Instead of duplicating every single operation and components, we opted for a build system that would allow us to annotate OpenAPI objects with versioning information. For example we have a `x-github-releases` extension that allows developers to include or exclude operations from certain releases. This extension is not present in our published descriptions since it is stripped by that build system.

We have other public extensions that add some GitHub-specific metadata to some OpenAPI objects. For example, we have an extension called `x-github-previews` which informs whether this operation is part of an API preview.

Other extensions are described in our open-source repository.

Is your team joining the technical developer community conversations to evolve the OpenAPI specification?

Not at the moment, but the recent overlay specification talks are of great interest to us. We will most likely join these conversations very soon.

Do you use other API specifications (ie. AsyncAPI, GraphQL, gRPC)? If so, can you share details of why?

We do! We use GraphQL as another public API which offers a different experience to GitHub’s domain and more flexible use-cases to our customers (more about this here). As mentioned earlier, we also use Protobuf for our internal Twirp APIs.

How did you convince leadership in your organization that OpenAPI was an important investment?

Fortunately, leadership was already onboard with using a machine-readable document to describe our APIs. We had extensive usage of JSON hyper-schema already, but the fast adoption of OpenAPI in the community and how it would allow us to describe our APIs accurately made us choose OpenAPI in the end.

In Conclusion

GitHub’s adoption of OpenAPI follows similar trends we are seeing with other leading API providers like Salesforce, Twitter, Plaid, and others. Multiple teams are realizing the benefits of using OpenAPI, with documentation being the number one driver, but then code generation and testing being second and third. API providers who are further along in their journey have realized that OAS doesn’t always do 100% of what they need and, like GitHub, are extending the specification and increasingly moving towards participation in the weekly technical developer community calls to help evolve the specification. It is gratifying to see leading providers like Github recognize and start to leverage the benefits of the OpenAPI Specification (OAS) for their business, and we look forward to having them more involved in the community.
If you’d like to share your OpenAPI journey story we’d love to hear from you. While many of the details between Plaid, GitHub, and other API provider stories are similar, it helps to tell stories from multiple perspectives and business sectors. If you have an OpenAPI story you’d like to share, feel free to submit a GitHub issue with your ideas, and we’ll consider adding it to the editorial queue. We wanted to thank GitHub, and Marc-André Giroux for letting us interview them, and share this great story with the OpenAPI community. Thanks to GitHub for providing us all with another example of why GitHub is a leader when it comes to how technology is delivered in the 21st century.

Jul 23
Love0

Postman Joins the OAI to Support the OpenAPI Specification

By Announcement, Blog

This blog post was contributed by Kin Lane, Chief Evangelist, Postman

When Postman launched its API builder last year, we were amazed to see how popular OpenAPI was with our users, when it came to designing and developing APIs. Our usage stats helped us realize just how important the OpenAPI Specification is to how our customers design and build their APIs. Today Postman is joining the OpenAPI Initiative in order to work with the 35 other OAI members to steer the specification forward. Together we will hope to continue to support open source tooling that builds on the specification and to grow a stronger OpenAPI community so as to ensure the future of this important industry standard. 

Historically, Postman collections were how API providers defined their APIs on the platform. With the introduction of the API builder, more API providers began using OpenAPI as the central definition of each API being developed. Over the years, Postman collections have evolved to allow developers to test, mock, document, and automate parts of the API lifecycle. Along with this evolution, each collection can be generated from an OpenAPI, pushing us to deliver a growing number of specific capabilities that help our customers leverage OpenAPI as the API contract for use across their API operations:

  • Import – You can import an OpenAPI document into the Postman and maintain it as the central contract for each individual API, which is used to validate and notify developers when documentation, collections, or tests are out of sync with the OpenAPI contract.
  • Generate – You can generate Postman collections from your OpenAPI definition, establishing derivatives of your API contracts for use in documenting, mocking, and testing your APIs in an ongoing fashion across regions.
  • Validate – Every collection generated from an OpenAPI specification can be validated across the OpenAPI contract, helping keep documentation, mock servers, and testing infrastructure in alignment across operations.
  • GitHub sync – When you are managing your OpenAPI document in Postman using the API Builder, you can sync it to GitHub, allowing it to be used in other systems, allowing changes to occur in Postman or via other tools.

OpenAPI has become part of the API factory floor for Postman customers. Beyond what a spec describes, Postman makes it easier to work with APIs by allowing you to store tokens or keys for multiple profiles or lifecycle stages and to augment with specific values for running tests or for monitoring. The OpenAPI Specification provides a way to define what is possible with HTTP APIs, with Postman collections emerging as a way to define, execute, and automate each stop along that APIs lifecycle. A stronger relationship between OpenAPI and Postman has helped our customers, and we’re thrilled to be joining the conversation about what the OpenAPI roadmap might be, and to help realize the full benefits of using OpenAPI across the API lifecycle.

Sep 17
Love0

The Blue Button API Will Be At APIStrat In Nashville Next Week

By Announcement, Blog

APIs are pushing forward the conversation in almost every business sector today, but one of the more important areas we are seeing across the landscape is coming out of the federal government with the Blue Button API out of the Centers for Medicare and Medicaid Services (CMS). We’d like to invite you to Nashville next week to learn more about the API efforts coming out of CMS, and how they are making an impact on healthcare in this country with APIs.

We are please to have Mark Scrimshire (@ekivemark) of NewWave Telecoms and Technologies, who is the Blue Button Innovator and Developer Evangelist for the CMS program. The Centers for Medicare and Medicaid Services (CMS) Blue Button API enables Medicare beneficiaries to connect their Medicare claims data to the applications, services, and research programs they trust through a suite of services, enabling:

– a developer to register a beneficiary-facing application
– a beneficiary to grant an application access to four years of their Part A, B, and D claims data

Providing API access to a platform that has the potential to reach 44 million beneficiaries, or 15 percent of the U.S. population who are enrolled in the Medicare program. Representing a pretty significant shift in how we think about the delivery of healthcare in this country. One of the most significant aspects of the Blue Button API when it comes to the wider API conversation, is their adoption of the HL7 FHIR standard in conjunction with OAuth 2.0 to provide access to the platform, setting the stage for a conversation around arguably the most important API definition available across the API sector today.

Join us Tuesday, September 25, at 10:00 AM, for a keynote from Mark Scrimshire about the Blue Button API, sharing the story of some of the successes and challenges with standing up the API platform. Mr. Scrimshire is just one of the can’t miss talks going on in Nashville next week. There are still tickets left, so make sure you get yours today, and do not miss out on the API conversation that is going on at APIStrat this year.

Aug 02
Love0

The First Batch Of APIStrat 2018 Nashville Keynotes Are Up

By Blog, Events

We recently published the schedule for APIStrat 2018 in Nashville, TN, and now we’ve published the first batch of keynote speakers for the event. We are pretty excited regarding the interest we’ve had in speaking at APIStrat this round, and the lineup we’ve managed to secure the main stage. Making for a pretty compelling set of voices for the 9th edition of APIStrat.

As we roll into August, we wanted to showcase four distinct voices we are bringing to the main stage in Nashville for this round of API Strategy & Practice:

Virginia Eubanks (@PopTechWorks)
Virginia Eubanks is an Associate Professor of Political Science at the University at Albany, SUNY. She is the author of Automating Inequality: How High-Tech Tools Profile, Police, and Punish the Poor; Digital Dead End: Fighting for Social Justice in the Information Age; and co-editor, with Alethia Jones, of Ain’t Gonna Let Nobody Turn Me Around: Forty Years of Movement Building with Barbara Smith. Her writing about technology and social justice has appeared in The American Prospect, The Nation, Harper’s and Wired. For two decades, Eubanks has worked in community technology and economic justice movements. Today, she is a founding member of the Our Data Bodies Project and a Fellow at New America. She lives in Troy, NY.

Kate O’Neill (@kateo)
Kate O’Neill, “tech humanist,” is founder and CEO of KO Insights, an award-winning thought leadership and advisory firm helping companies, organizations, and cities make future-aligned meaningful decisions based on human behavior and data. Author of 3 books including PIXELS AND PLACE: Connecting Human Experience Across Physical and Digital Spaces, Kate speaks regularly at industry conferences and private events, providing keynotes, participating in panel discussions, and leading creative brainstorming workshops for groups of all sizes.

Jenn Schiffer (@jennschiffer)
Jenn Schiffer is an engineer, artist and tech humorist. Most people know her for her incredible strength and also for being the Community Engineer of http://Glitch.com at Fog Creek. She organizes JerseyScript, a monthly web developer social in Jersey City where she’s based, and built everyone’s favorite free online pixel art editor, http://Make8BitArt.com .

Cristiano Betta (@cbetta)
Cristiano is a Developer Experience designer who helps companies small and large to improve their developer onboarding, activation, and support. He likes to look at great developer onboarding flows, analysing and documenting the best practices and pitfalls of common design practices. Although he has over 15 years of development experience he believes that at the core we’re all beginners at some things, and documentation and onboarding should reflect that notion. In the past he’s worked as a contractor, startup founder, event organiser, and developer advocate at PayPal.

We worked hard to continue bringing the leading API voices from across the space, but we felt it was also important to push forward the conversation on important issues that are relevant to the wider tech sector. We feel these four voices reflect the type of event we think the API sector needs in 2018, adding to the diverse set of personalities we’ve already brought together as part of the APIStrat session and workshop lineup.

Make sure you don’t miss out on the conversation this September 24th through 26th in Nashville, TN. Get registered for APIStrat 2018 today, and spend some time looking at the session and workshop lineup we have planned. We have more announcements coming so stay tune, and there are still opportunities to support APIStrat as a sponsor, so that you can help make sure the conversation that has been going on since 2013 continues.

We look forward to seeing you in Nashville September 24th through 26th!

Jun 08
Love0

We Are Extending The APIStrat Call For Papers Until Sunday At Midnight

By Blog, Events

We have gotten the usual rush of last minute folks worried if they’ll make the deadline for submitting their talk for APIStrat in Nashville, TN this September. We fully understand that people are business, and the deadline may have snuck up on them, so we are going to extend it until the end of the weekend, to give folks more time to slow down a bit and think more about their talk Saturday and Sunday.

It is important to us that you can get your talk in. While we do make some exceptions for late talk submissions, they aren’t always accepting because they don’t end up being reviewed by the entire committee. So, we encourage you to take the time and craft up the best title and abstract possible, and complete the CFP flow available on the website. Once submitted your talked will be reviewed by our rockstar lineup of judges.

We are looking forward to seeing you all in Nashville, TN this fall. We know that you have amazing stories that should be shared with the community, and are looking forward to having you on stage at APIStrat. This 9th edition of the API community conference is going to be one of the best yet, and as always we are looking for the most diverse API stories possible, with a lineup of speakers to rival previous years. Don’t miss out on this opportunity to help shape the ongoing API story that unfolds across the industry, which is being shaped by APIStrat and the OAI foundation.

Jun 01
Love0

Only One Week Left To Submit Your Talk For APIStrat In Nashville

By Blog

We are fast approaching the CFP deadline for APIStrat in Nashville, TN. The CFP form will close next Friday, June 8, 2018 at 11:59 PM PST, leaving a little over a week to share you story with the program committee for possible inclusion in the lineup.

APIStrat 2018 is the 9th edition of the conference, and the 2nd one being hosted by the OpenAPI Initiative. Helping ensure the conference continues to be the place where you discuss the common practices, as well as ground breaking trends that occur across the API community.

How to Submit

To submit your talk, we are just asking you begin by answering three questions:

1. How will the audience benefit from your presentation?
2. Why should YOU be the one to give this talk? You have a unique story. Tell it.
3. Be prepared to explain how this fits into the API ecosystem.

After that we are looking for topics that fall into some of the common areas of discussion occurring within the API community:

  • API Design – The design of APIs following REST, Hypermedia, or any other common pattern.
  • API For the Greater Good – Helping ensure that APIs are making a positive impact on the world.
  • API Management – All about API portals, documentation, authentication, logging, rate limiting, and other management needs.
  • API SDKs & Clients – Looking at the common practices involved with providing SDKs and clients in a variety of languages and platforms.
  • API Security – Considering security practices for APIs going well beyond just API authentication and management.
  • API Success Stories -Looking to share some of the success stories from within companies, organizations, institutions, and government agencies.
  • API Transformations – Considering how APIs are being transformed, evolved, mapped, and turned into exactly what they need to get the job done.
  • API Testing – Taking a look at the monitoring, testing, performance, and other aspects of ensuring APis are doing what they should be.
  • API Usability – Thinking about how to make APIs more usable and friendlier to developers, consumers, and stakeholders involved in the API lifecycle.
  • At The Protocol Level – Diving into the technical details of HTTP, HTTP/2, TCP, and other protocols in use to deliver APIs in the real world.
  • Digital Transformation – Looking at the organizational and cultural side of how we transform our organizations to operate more efficiently in the digital age.
  • GraphQL – Taking a look at one of the latest trends in API deployment that focuses on the more data-centric delivery of API resources.
  • Hypermedia – Learning about how APIs are just the next evolution in the web, and deliver on many of the affordances we take for granted with the web.
  • Machine Learning – Understanding the intersection of using APIs to deliver machine learning, artificial intelligence, and forms of magic emerging on the horizon.
  • Microservices – Looking at how APIs are being delivered based upon specific domains of knowledge, ensuring that they do one thing, and they do it very well.
  • REST – Continuing the discussion around how REST can be used to deliver simple, usable API resources that leverage the web as a transport.
  • RPC Systems – Acknowledging that there are many different design patterns in play in the real word, and discussing the pros and cons of RPC implementations.
  • Standards & Definitions – Taking a look at the standards and common definitions that are being put to work across different industries, and organizations of all shapes and sizes.

That should provide you with a pretty nice menu of options when it comes to crafting your talk submissions. However, don’t let these topics railroad you. Feel free to think out of the box when crafting your talk. Each year we add new topics to this list, and maybe your talk will be the one that pushes this years list forward. Make sure whatever you decide to talk about that you are thinking outside your world, and make it something that the community will learn from, and be something they can take home with them after the event. While the subject matter, and speaker is important, ensuring that conference attendees go home with new ideas in their heads it what matters the most–make it count.

We Want to Hear From You

Ok, you have until next Friday, June 8, 2018 at 11:59 PM PST to submit your talk. Get to work! We know you have some amazing ideas to share with the APIStrat community. If you’ve missed earlier events, Nashville will be the place where you can make your mark. Head over to the APIStrat CFP form, and bookmark it for when you are ready.

If you have any questions feel free to reach out–we are happy to answer any questions about what we are looking for, and share stories about previous events if you haven’t attended before. And, we look forward to seeing y’all in Nashville this September!!

 

May 31
Love0

A Shout Out to the APIStrat Steering and Program Committees

By Announcement, Blog

We are getting ready to close the APIStrat call for papers next week and we wanted to take a moment to give a shout out to the amazing lineup we’ve assembled as part of the steering committee, who are helping guide the event. As well as the folks on the program committee who will be helping review the talks submitted as part of the CFP process, and ultimately craft the program. These are the people who will help set the tone for the conversation that occurs at APIStrat in Nashville, and we are very pleased to have them helping out.

Here are the members of the APIStrat steering committee, playing different leadership roles in the conference, making sure everything gets done by September:

Steering Committee

Next up, we nineteen folks on the program committee who you will have to WOW with your talk submissions so that you can get on stage at APIStrat in Nashville:

Program Committee

Thank you so much to everyone involved. It takes a lot of work to pull together an event like this. Everyone involved is participating because they believe in the event, as well as the health of the wider API community. Once again, we feel like we have assembled a pretty amazing lineup of folks to help make sure APIStrat adequately represents the community, coming from a diverse range of companies delivering APIs and services to the sector.

While the primary roles for the event are filled, there are still plenty of opportunities to get involved. First, make sure you have submitted your talk–you only have one week left to get it in. Second, there are sponsorship opportunities available, and we need the financial support of the API community to be able to make the event happen again. Feel free to reach out, and we’ll see what we can do to get you involved, and part of the goings on in Nashville this year. Thanks again to our steering and program committee members, and we’ll see you all in September.

Close Menu