API First Workflow: How could we have better API Docs through DevOps pipeline

Editor's Notes

• #3: This is what we’ll talk about today. Very short agenda. We’ll touch *briefly* on what our current process is and the challenges that it brings, and then we’ll levelset on what API First is and how it alleviates those challenges. And then we’ll talk about our Vision of bring API First to SAS from a development perspective.
• #4: So to start, this is a very simplified diagram of working in a code first basis. It’s a very traditional way of developing. A very siloed way of working, backend developers write the code, and then they throw it over the fence for testers, and somewhere along the way the developers are writing. And then poor Jeannie is left to review the an api she has not business context of. Very siloed, very manual - there’s challenges to that. there are times that are published documentation doesn’t sync with our code / software And finding a design flaw here can be very expensive because the code has already been written This would also bring too much work for the reviewers to review the docs, especially before the release date, If some terrible issues come out which are not suitable for shipment, they will not have enough time to fix them In this climate, this isn’t the most effective way to work. The adapting CI/CD was brought up countless times for many companys, and API First in one of the ways we can work toward that’s.
• #5: The API First would changes the API developing process form developer led to a product-led, so with API First, instead of the old way where it’s ansynchrounous and siloed, - you have something more like this
• #6: Instead of silos, you have teams working synchronously. And this is all made possible by starting with a OpenAPI 3.0 Specification. When you start with a spec, you give all these folks a starting point. What you’ll also notice that’s mentioned here but not mentioned in the previous slide, the heavy influence of a product manager. They’re the decision makers and driver here- so moving towards a product led company. They will be involved with the designing of this spec. When you start with design, You make development bend for the design, not design bending for development. What’s really nice about openapi 3.0 spec is that it’s machine readable so that opens us up to many opportunities to automate testing, and documentation, and to some degree code generation. So, we have a few teams that are ahead of curve and already working like this to a degree. it. Of course there isn’t a standard for this so they all kinda went off and did their own thing- And what we’ve done is we collaborated with them and we got their feedback on it so far. And it’s been working really well for them. The testers are happy, the developers are happy. So we studied their process and we evolved it understand what’s working and what’s not- what opensource tools do they like and don’t like. And they gave us a starting point, from there we designed an API First workflow that can be a standard at the company. Before we talk about what that api first process looks like these are the values that we always kept in the back of our minds when creating it.
• #7: An API process that…. Increase efficiency : more opportunities for teams to work in parallel, also efficient in the sense that if a better api tool comes out tmmrw, it should be easy to switch out tool so a very flexible architecture too. More opportunity for automation: The fact that the spec is machine readable allows us to be able to automate testing, documentation like never before Increase Usability for our end users: putting design first so our apis are trivial to use. Being able to refer to documentation easily to help the customer understand the apis This is our mindset we went in with when we were planning how we want to bring API First into our organization. What we’re going to go through next is that API First workflow that we have envisioned for SAS And this is the design we work towards every day to implement.
• #9: 1. Since the api specification is both machine readable and human readable, it could be leveraged by api tools for various purpose
• #10: Right, so this is the people and the process So this is the who and the what. If we direct our eyes to the key, a purple diamond is a human (developer, tester, technical writer), and the square is a robot. Linting- guardrails to ensure their writing an effective spec Mock server: gives the person who writing the spec an idea of how the api would look and feel. They make api calls to this mock server and it actually returns mock data. So you can really get a feel like does the way this api works make sense Testers: a mock server is started for that approved API spec. The testers are notified- hey the mock server is up for the api spec- go test it. What that means is the testers can test the api, and create unit tests for that api before it’s ever even built. So then later, when the api is actually built- they can just use those same test cases for that code Client code is generated: what does it look like to call this api in python Documentation is generated: gives the technical writers a starting point- that generated doc would already have examples in it and what not Server code generated: finally, a boiler plate server code is generated for the developers to extract from and add more meat. We spent a good amount of effort vetting out server generator code tools. And the one we landed on, the idea is that it generates a file of A boiler plate meaning that it takes the functions from the spec and creates the functions signature in go for the developer to add logic to. After the developer adds logic, contract testing happens. Does the code match the contract (the spec) no? developer has to redo logic. Yes? Then it passes and the testers test the code Analytic cloud team was saying that they’ve seen a huge increase in productivity here because the testers can use the same tests they used against the spec, against the code So this workflow is the people and the process, next Yantian is going to talk about the technology. She’s going to talk about our “how we’re bring api first to sas” at a more granular level specifically about the pipeline