Episode 68: OpenAPI with Tony Jiang | Salesforce Developers Podcast

Tony Jiang is an Associate Product Manager for Salesforce. He joined an Associate Program right out of college. In the program, he’s learned about product management and he is now in his first rotation working on platform APIs.

In this episode, Tony and I are talking about implementing the OpenAPI specification, an ongoing project here at Salesforce. We discuss what it is and the various benefits that come with it. Tune in to learn all about how it will impact you.

If you’d like to participate in the “OpenAPI 3.0 Spec for sObjects REST Resources” pilot, contact your Salesforce Account Executive or open a support case. Your feedback is very important to us, so that we can give you the best developer experience possible. 

Show Highlights:

  • How Tony got involved in the Associate Program.
  • What made him want to transition from engineering to product management.
  • What OpenAPI is and where it originated from.
  • The advantages of implementing OpenAPI.
  • How OpenAPI implementation will affect other projects.
  • How they are developing OpenAPI right now.
  • How OpenAPI supports Apex REST.
  • The relationship between External Services and OpenAPI.
  • How to get access to the spring pilot version of OpenAPI.
  • The impact OpenAPI will have on SDKs.

Links:

Episode Transcript

Tony Jiang:
All of a sudden, I just found this new world. I feel like it’s extremely interesting and powerful. It enables people to build interesting scenes and overall, it’s just super fascinating to me.

Josh Birk:
That is Tony Jiang, an associate product manager here at Salesforce. I’m Josh Birk, your host with the Salesforce Developer Podcast. And here on the podcast, you’ll hear stories and insights from developers for developers. Today, we sit down and talk with Tony about the OpenAPI implementation that is ongoing here at Salesforce and some of the great advantages with it. And we start with how Tony got into Salesforce.

Tony Jiang:
So yeah, definitely Tech Soft, Virginia was something that I was interested in and to be Frank, when I first applied for jobs, I first originally applied to Software Engineers, to many companies, a lot of small fates or interesting events that got into product management. But yeah, definitely in Tech and Software.

Josh Birk:
Okay. Well, first let’s go… Even before that, what was your earliest experience with computers?

Tony Jiang:
Earliest experience? I think probably in elementary school if not earlier, but I definitely know elementary school. There’s a course that teaches you about computers and some softwares, Words, or things like PowerPoints and others.

Josh Birk:
Got you.

Tony Jiang:
Even courses that teach you about typing. So probably my first experience.

Josh Birk:
Nice. Okay, so then let’s go back to that other point. This is your first full-time job out of college, right?

Tony Jiang:
Yes

Josh Birk:
And how did you get involved in the associated project… I’m sorry, the associate program… Is it program manager or product manager?

Tony Jiang:
Product.

Josh Birk:
Product manager. Tell me a little bit about that program and how you got involved in it.

Tony Jiang:
So yeah, the program was started originally by our CEO, Brad, when he was still the chief product manager. And he was originally, one of the earliest associate product managers at Google, when he started his career. And when he joined Salesforce and he was maybe in the product organization and he really wanted to have more younger product managers be a part of Salesforce and grow with the company because he had such a great experience at Google. So he started this program.

Tony Jiang:
So the program is targeted for young, just new grad students just finished college or who has a background in engineering or technology that are interested in product management. It’s a very tiny program. Each year they take about 12 new students from college and yeah, just a super fascinating experience you get. So this is a rotational program, so two years and you rotate on a different team every eight months. So this is my first rotation here at Salesforce working on platform.

Josh Birk:
Got it. Okay, so two follow-ups on that, and then you actually just segue to my next question. Because I was looking at your resume, it’s like you were moving from, I think… Where did you move from when you went to the API team? Let me just start-

Tony Jiang:
So I was a associate product manager intern last summer at Salesforce-

Josh Birk:
Fantastic. Okay.

Tony Jiang:
… and I was on marketing cloud working with the interaction studio team. So over there, the project I worked on is actually building integrations with Salesforce because [inaudible 00:03:36] specifically interactions too is actually entirely separate technology stack and has its own softwares. And we are trying to build integrations with Salesforce using the Salesforce platform technology, so it’s very interesting.

Josh Birk:
Got it. Got it. So the whole thing fascinates me because as somebody who got into software engineering almost accidentally, I was like a child of the Internet, I needed to go find a job. So I started freelance, like creating websites and stuff like that. But the concept of being a product manager had never really occurred to me until I started working at a bigger corporation basically. So what attracted you from engineering to product managership?

Tony Jiang:
Yeah, so my first product manager internship was definitely accidental, but through that experience, I learned. I enjoyed many aspects of product development, so not just about building stuff, but also coming up with ideas, talking to customers, especially beginnings. And learning their pain points, their needs, their jobs to be done and then coming up with ideas of solving them. And then putting pieces together, building out a roadmap for it and working with cross-functional teams to make that happen. And eventually seeing that payoff through the smiles of our customers, which is tremendously rewarding. So as a whole cycle of product development and many aspects of things, not just building, really attracted me to product management

Josh Birk:
Nice. Through the smiles of our customers, I love that. That is awesome. Okay, so let’s talk a little bit about your current work. You’re currently on the API team and you’re focusing on OpenAPI, right?

Tony Jiang:
Correct.

Josh Birk:
So tell me a little bit about OpenAPI. What is it and where did it originate from?

Tony Jiang:
Yeah, so OpenAPI, it’s the industry standard format for describing and documenting RESTful APIs. It’s in JSON or YAML format, so it’s machine-readable. And if I can show something, it will be more clear. But essentially in documents, everything about the API, the single source of [inaudible 00:05:51] code API. Things like, what are the end points or UIs you can call for that API? What are the authorization methods you can have for each end points? The expected outcomes for a given API and also what are the parameters you need to provide? So it provides a a way for developers to documents their APIs in a very systematic way.

Josh Birk:
Got it. Got it. So does it change or influence the shape of the API at all or does it just sit adjacent to it?

Tony Jiang:
It’s adjacent, so as long as you have a RESTful API, it can be described or represented in OpenAPI specification.

Josh Birk:
Got it. Got it. So I think, a little bit of that to a developer, probably is obvious, but what’s the big advantage of implementing something like this?

Tony Jiang:
So one of the biggest advantage I think, is it is industry standard way of describing it. So a lot of developers will have already learned OpenAPI for the first time or have used them before. Once they have known the schema construct or how it works, they will have a much easier time when they see an OpenAPI for some other APIs again, in their career. So if they have seen an OpenAPI for Zoom’s API and when they see one for Salesforce, they’ll be able to really understand how things work. So it makes it easier for them to understand and comprehend APIs in that standpoint. And on top of it, there’s a whole suite of open source tools often under the name of Swagger that consumes OpenAPI specifications and allows many things to happen from that, so you can have interactive documentations be generated after consuming the specs so that developers who are new to learning about the API can just visually understand through some type of UI, how MTR works.

Tony Jiang:
There’s a tool called Swagger Codegen, once you open a specification to it, you can automatically generate STKs or packages in whatever language chosen by the developers that they can embed into their own systems and call those APIs really easily without writing any custom code. So there’s a lot of really nice used cases and industry standard tools that makes leveraging OpenAPI specification extremely important.

Josh Birk:
Nice. I got to say hearing all of this and especially that this sounds like a super modern version of Whistle.

Tony Jiang:
Yes, it is actually. So when I first got onboarded to the team and I was learning about everything, I was like, “Oh, there’s already the Whistle file for the soap API.” And my manager told me this is in a way similar to have a specification for the REST API and we’re calling it OpenAPI.

Josh Birk:
Got it. Got it. Let’s talk really specific, because I know there’s another project. Some of my colleagues have worked on with it, where they’re trying to get collections up and running on Postman so that Postman can be an easy mock/rapper for our API. What kind of influence will this have on that kind of project?

Tony Jiang:
Yeah, so we already have a Postman collections for Salesforce’s API that were put together by ourselves as Salesforce developers, Salesforce communities. It’s all great. But often they might be missing APIs that we have recently launched, or it might not constantly be updated. It takes effort, I will say, but if we have a draft specifications for the Salesforce API that are constantly being updated by us, or is generated against the code, then someone can easily consume that Albany specifications that we produce when we support a client like Postman, to auto-generate those collections automatically without having someone to craft it themselves. So it makes it a little bit easier to manage such a package.

Josh Birk:
Yeah. Okay, so instead of having to A, know that the API has been updated B, remember you have to go change your collection, spec C, update all of that JSON and everything else that Postman’s doing and then push it out to GitHub. It almost sounds like you could put that into like a build, deploy at this point.

Tony Jiang:
Mm-hmm (affirmative). Yeah, and also Postman is one use case of OAS, OpenAPI specifications. There’s whole bunch of other use cases. I do find the collection that has already been created by our developer communities on Postman’s, it’s already really useful in that case. Maybe the OpenAPI use case for Postman is not as useful. The marginal benefits are a little less, but for some other use cases, it’s definitely something that they don’t have access to before.

Josh Birk:
Got it. Got it. Okay, so tell me about the current state of the OpenAPI project and then we can talk roadmap in a little bit. But what kind of pilot is it in right now?

Tony Jiang:
Yeah, so we started our journey, it was OpenAPI a couple of releases ago. And we are focused on initially, with the sObjects API for our REST API. And we are simply, right now for our pilot phase, just trying to represent for sObject API resources in OpenAPI specifications as pilot, and then showing that pilot OpenAPI specifications to a select group of pilot participants. So that’s our current state and in spring ’21, we are still focused on the same side of pilot resources we’re testing out. But we are moving towards this new kind of work specific specification. So previously, in the previous pilot, we created a single static spec that we are simply showing on GitHub.

Tony Jiang:
So we give all the pilot participants access to the GitHub repo so they can come and take a look at that spec. But now what they can do is they can call a OAS generation end point directly against their org so that whatever OpenAPI spec it generates, contains org unique API end points information based on their org shade, based on their custom objects that they have created. So because Salesforce is so unique in terms of its infrastructure and the multitenantness, makes a lot of sense for that to happen. And especially going forward, there’s org specific API end points that our developers create such as Apex REST. And for those, it definitely needs to be org specific. The specifications they produce has to contain unique end points that only that org has versus the standard ones.

Josh Birk:
So current state, it’s like, “You can kick the tires” but you’re basically just giving them a blueprint for them to just run, probably just random testing and just see what it’s like, and future state is they could actually start sand boxing some implementations that actually respects their data model and their current functionality?

Tony Jiang:
Correct. So today is, that’s our initial pilot. It’s like a sample. So you can take a look at how it would look in the future. How would this look when we have more resources represented. Just how we’re going with this and the next pilot or the next iteration, it’s more similar to the Whistle generations. If you’re familiar with this, you can click a button and then it’ll create a whistle for that org and then we’re doing something similar for OpenAPI specifications as well.

Josh Birk:
Got it. And in going back to that Apex REST point, because I have to say Apex REST is like one of my favorite things on the platform, just like a super powerful way of creating custom REST end points. Any limitations there, for the future roadmap, when it comes to what I can do in Apex REST versus what OpenAPI can basically? Describe.

Tony Jiang:
So we, haven’t got to kind of spiking on or trying to dig into the details of whether we can support OpenAPI specific agent for Apex REST. But we have learned from a lot of our partners, a lot of our customers that it is a highly important feature to have. Because they’re creating their own APIs using Apex REST, they want those APIs to be documented, so OpenAPI specification, so they can hand it off to their stakeholders. Especially important for partners so they can hand it out to their customers. So we have learned that it’s extremely important for us to support OAS for Apex REST and we will definitely look into that in future releases.

Josh Birk:
Okay, so hashtag safe harbor-

Tony Jiang:
Yes.

Josh Birk:
… a bright spot on the roadmap that you’re looking forward to. Got it. Got it. So I want to talk a little bit more about roadmap in a bit, but also curious about how this works the other way around. Does this have an impact on external services or flows ability to consume REST APIs or anything like that?

Tony Jiang:
So in its current state, we don’t have any connection to [inaudible 00:15:22] services. Aside from that, they also rely on OpenAPI specifications.

Josh Birk:
Got it.

Tony Jiang:
But we do say that with Salesforce we really think that OpenAPI, it’s a really powerful tool, right?

Josh Birk:
Mm-hmm (affirmative).

Tony Jiang:
It is a schema that outlines how you can call an API to integrate with systems. And we want to make integrations as easy as possible. And the narrative around this is that what I’m working on, which is the production side of the spec, is the outbound version of integrations. How can other systems use our APIs easily? How can we enable developers to easily integrate, try out, mock against our APIs? Make that as easy as possible. But on the other side, we want to make inbound integration as easy as well. And other companies, other great external web services are highly useful for our customers and partners as well. And they are also being described by OpenAPI specification as it is industry standards. So external services makes it extremely easy to connect Salesforce with those external web services by consuming OpenAPI specs and turning them into irrevocable actions that admin or developers can embed into or try out in flow builder as flows.

Josh Birk:
Got it. Nice. And so talking back again about that outbound, are there other… So you’re talking about Apex REST, you’re talking about the sObject API, or are there other APIs that you’re looking to expand out to?

Tony Jiang:
Yeah, so the biggest vision is that we you want to ensure that all Salesforce is API. Physically, the entire REST API, as well as other Salesforce kind of companies or services APIs, we want to make sure that all of them are going to be represented by OpenAPI specification. My project specifically focuses on the core REST APIs, which is a big chunk of our platform API. So the bulk composite sObjects, eventually we want to represent them all in OAS, but it is going to be a journey for sure. And we want to focus on the ones that are the most important and learn from our customers and partners, which ones are the most important for you to have OpenAPI specs for. And so we can focus on the first.

Josh Birk:
Got it. And are any of these changes going to have an impact on creating legacy APIs or any current legacy APIs or anything like that?

Tony Jiang:
No, we are currently just supporting the latest versions of the API. So when you generate OpenAPI specifications, you will only be creating a spec for the latest versions of Salesforce APIs.

Josh Birk:
Got it. Okay, that makes a lot of sense. Anything else on the roadmap that you want to give a shout out to?

Tony Jiang:
I think just look forward to having all the APIs being represented by OpenAPI specifications. And yeah, we’re really excited about Apex REST. We did really learn a lot from our customers. A lot of the pilot market trends that we have worked with that it is something that they need support with and we’ll definitely look into how to do that soon. And it would definitely move up in our priority list, just because we have had so much voice about it.

Josh Birk:
Got it.

Tony Jiang:
But down the road, just expect all Salesforce APIs we’ve represented OAS and please let us know which ones are the most important for you, so we can optimize and get to that goal in the shortest paths.

Josh Birk:
Nice. So tell me a little bit more about some of the changes between winter and what we’re looking forward to in spring. Like for instance, I think we’re going from 2.0 to 3.0, is that correct?

Tony Jiang:
That’s for external services. So for external services-

Josh Birk:
Got you.

Tony Jiang:
Yes, the previous versions of external services only support OpenAPI 2.0. We’re coding in pilot for supporting OpenAPI 3.0, so it’s the newest version of OpenAPI. So this, yeah pre-sales services.

Josh Birk:
Pre-sales services. But your project is hitting the ground running with 3.0?

Tony Jiang:
Yeah, we started off with 2.0, and we also do have two pilots, the winter 21 and the spring 21. The winter 21 is the one I talked about, which is just a sample spec. We provide how it will look for the floor. I solved the resources in OAS, ensure it so we can have repo. For spring is the org specific OpenAPI specifications. How do you generate a spec that reflects your work, unique shape and end points? That’s the focus of the spring pilot.

Josh Birk:
And so looking forward to that spring pilot, how could people request access to that?

Tony Jiang:
Yeah, so please reach out to your account teams and ask them to nominate you to be a part of the pilot. And then once they nominate you, we can get in touch and I’ll walk you through the onboarding process.

Josh Birk:
Nice. And if people want to see some of this stuff in action, you have a demo back at DreamTX, can you give me the five penny tour of that? What were you showing off in that demo?

Tony Jiang:
So we actually demo’d two demos during DreamTX. One is the, the use case was Postman. So the focus there, and the problem with solving there is time to value for APIs and trying to understand the API. So a lot of developers for our new two Salesforce platform, who are new to the REST APIs. They need to read the documentations and it takes them a lot of time to really get onboarded. But a lot of times they don’t have that luxury to take half time to really get to speed. But if they have already experience with OpenAPI and they already know the various tools such as Postman, that allows for auto creating collections for APIs, they can just generate a OpenAPI specs for the APIs they are interested in.

Tony Jiang:
Currently we only support sObjects, but in the future, if you guys are interested in. And then creates documentations or auto-generate collections and Postman’s, so that they can start learning about how the API works, mocking against it, testing against it, or the minutes without just simply looking at the documentation developer guide and have to write custom codes to try it out. So it’s really a experience to help them get on and ramp up with the API as quickly as possible.

Josh Birk:
Nice, I love that in part, because I remember the interview I had with [Nita 00:22:10] Rosen, and she was like, “The first thing to start a project is just to start hitting the REST APIs and just see what they actually do. And throw data at it and get the data back.” And one thing was like, “Don’t necessarily trust documentation” because the REST API is the actual, like the thing that you’re actually going to be talking to and everything that you just said there solved so much at that because it’s faster to learn and you’re auto generating the docs based on the actual API. So that’s also going to be more stable.

Tony Jiang:
Yeah, just add a little bit color here. So if you just read the documentation, it’s great, it’s comprehensive, we provide examples, but we can’t cover everything.

Josh Birk:
Mm-hmm (affirmative).

Tony Jiang:
So one example of something that shows up with API specification, because it’s generating a code, that’s not on the developer guide is, if you’re calling the sObject API to create account on the developer guide, you’re going to see a templatized UI that says, you can tell us what the object name you want to create a record for and then you can just do that. But because there’s so many objects, they can tell you what is specifically the parameters or the inputs required for whatever object you want to create. But in OpenAPI specifications, because they’re generated against a code and generated against the objects that are available in your org, you’ll be able to find specifically the UI for that record you’re interested in.

Tony Jiang:
So let’s say you want to create accounts, when you go to that section of the OpenAPI specifications and list out the parameters and the fields it requires for creating a record of the account objects and list it out. So the different fields it needs, the name, I don’t know exactly the other fields, but it will tell you what are the fields required. And it shows that in the collection that’s auto-generated in Postman. So that when you are trying to create a record for off the record in Postman, you can just kind of read it and then just replace it with the mock data you have to quickly try out.

Josh Birk:
Okay, so that was one demo. There were two demos for DreamTX, what was the other demo that we showed?

Tony Jiang:
Yeah, so the other demo focused on a slightly different developer persona. So the first one was about the API Explorer, persona someone who’s new and doesn’t know much about the REST API, but this one is focused on Salesforce developer already in the widths of trying to create integration. So I did hear the host of the episode show an example of how a developer can fast track the application development life cycle by consuming a OpenAPI specs in Swagger Codegen, the two I talked about earlier that allows developers to auto-generate an STK or a package of the APIs in whatever language they select.

Tony Jiang:
In the case of the demo there it was, I think I did see I was creating a Node.js Backend and they want to be able to call the sObjects, HEIs in Salesforce. So what he did is he took the pilot spec that we are demoing and he just generated a STK, then installed it into the Node.js app that he had. And the really simply be able to call that and then make calls against the Salesforce APIs without writing actual code to make the calls themselves.

Josh Birk:
Nice.

Tony Jiang:
So extremely powerful and took him like five minutes to make the app happen.

Josh Birk:
That’s awesome. So I actually do have a follow-up question because it just occurred to me how much this work sounds like it overlaps some of the work we’ve done internally, like when it comes to creating a mobile STK. Is there going to be an impact on some of the other STKs because they’ll be able to take a leverage on this or take advantage of this?

Tony Jiang:
I think the mobile STK, I’m not super familiar, but it definitely has a focus on mobile and it’s unique features for that. But for this it’s focused on the API, so you can use these STKs in whatever applications you have. You don’t even have to use it in applications. I heard it from our customer, their use case is to auto generate those kind of STKs for integration testing.

Josh Birk:
Got it.

Tony Jiang:
So before they had those integrations that rely on Salesforce API, and they have to manually write all these integration tests themselves. But if with the STK, it auto-generate all those kind of messages for them so they can… Easy tested without writing much code.

Josh Birk:
And that’s our show. Now, before we go, and even before we talked about Tony’s favorite non-technical hobby, I just want to give a quick shout out to the weekly charity fortnight match that I have started playing. We’ve actually been doing it for a while, to be honest, with some of your favorites, like Reed [Karlberg 00:27:04], Heather storm and James Lowry. If you want to catch that it’s twitch.tv/joshbirk. And we try to do it every Thursday, five o’clock Central Time. Now I did ask after Tony’s favorite non-technical hobby, and it turns out it’s basketball. And like so many people, it’s been impacted by the pandemic. All right. Nice.

Tony Jiang:
Now it’s hard time to play because everything locked down, but the courts are shut down. But yeah, before I like to just play around, shoot around with some friends or just play with myself. Kind of a way for me to meditate on my own. Yeah.

Josh Birk:
I want to thank Tony for the great conversation and information. If you check out the show notes for this episode, you can get more information about the OpenAPI program and including a couple of tips on how you could get into the pilot. Now, if you want to learn more about this podcast in general, head on over to developer.salesforce.com/podcast, where you can hear all the episodes, see show notes, have links to your favorite podcast service. Thanks again. I’ll talk to you next week.