API First Workflow: How could we have better API Docs through DevOps pipeline
•Download as PPTX, PDF•
1 like•331 views
API Documentation plays an important role in improving the customer’s experience with APIs, which is always a struggle for most of the company. The way to accomplish this is to transition API development culture from “Code First” to “Design First”, here in SAS we call it “API First”. For better API designing and documentation, we have built an API First CI/CD workflow which brings many open-sourced API tools together and involves developers, product managers, documentation writers, and testers to synchronously work together to develop APIs in a “Design First” approach, the industry standard. In the talk, we will discuss how the API-first Workflow could enable better collaboration between teams which could help in many aspects especially writing the openAPI documentation, keeping it up to date and sync with your code. We will take a deep look at one example, the Linting tool from API First workflow, which helps to make sure the API documentation follows the company standard from the start. With openSource linting tools like Spectral, it’s easy for teams to define their own linting rules which includes company standards. When your API specifications go through the linter in the CI/CD pipeline, the linter will throw errors and warnings as you write your spec. This will help ensure your specification is following proper guidelines and that’s all automatic.
More Related Content
What's hot
What's hot (20)
Similar to API First Workflow: How could we have better API Docs through DevOps pipeline
Similar to API First Workflow: How could we have better API Docs through DevOps pipeline (20)
More from Pronovix
More from Pronovix (20)
Recently uploaded
Recently uploaded (20)
API First Workflow: How could we have better API Docs through DevOps pipeline
- 1. API First Workflow: Better API Docs through a DevOps pipeline Yantian You yantian.you@sas.com API Integration Engineer @SAS
- 2. AGENDA 01 02 Current API Process (Code first) vs API First (Design First) API First Workflow / Vision 03 Use cases and examples
- 5. Developers Documentation Continuous Delivery OpenAPI 3.0 Specification Testers Product Manager Design First
- 6. API First Roadmap Planning Mindset Automation (CI/CD) Efficiency Usability
- 8. API Design API Specification Tool chain APIs tests documents Code template Mock services Cloud Platform Security check Other docs A Quick Overview
- 9. Development Cycle Continuous Integration Mock Server Lint Team Review Rejected Approved Merge to Master Server Code Generated (Boiler Plate) Mock Server Started Documentation Generated Development Cycle Continued Testers / PreSales Tech Writers Edits Contract testing Testers test Code Developer adds logic Commits code Tests Fail Tests Pass Final Team Review Publish API Write OpenAPI Pull Request Client Code generated API Spec Key Human Automatic / Machine Done Fail Pass … Let’s go deeper into it
- 10. Design Workshop Stoplight Studio Swagger Editor Apicurio Spec gen tool(Web/GUI) Opensource API Specification Product manager + Customer + Stakeholder + Testers + Developers How to get an API Spec at the very beginning?
- 13. Development Cycle Continuous Integration Mock Server Lint Team Review Rejected Approved Merge to Master Server Code Generated (Boiler Plate) Mock Server Started Documentation Generated Development Cycle Continued Testers / PreSales Tech Writers Edits Contract testing Testers test Code Developer adds logic Commits code Tests Fail Tests Pass Final Team Review Publish API Write OpenAPI Pull Request Client Code generated API Spec Key Human Automatic / Machine Done Fail Pass Let’s talk about the automation part
- 14. API Dev Mock server Server code Client & Test Deploy on k8s cloud server Push to git platform Review & pull the branch Doc gen Input Deepmap OpenAPI - Gen Swagger- Gen Code gen tool (Containers) Prism Apisprout Mock tool (Containers) Opensource Opensource Doc Initial Spectral Opensource Linting tool(Containers) API Spec Spec linting Test & Review & Merge contract/smoke/unit Test
- 15. Input API Spec Tool Box 1 Tool Box 2 Tool Box 3 Tool Box n For local run and testing: Tooling containers & Sage tools(= Sas + mage) For running in the pipeline: Using the same tooling containers OpenSource tools in the pipeline
- 16. Use cases and examples
- 19. Building the mock server Take API Specification as the input, run prism tool for building a mock service • Build the mock server locally • Build the mock server through the pipeline - auto-deploy to a k8s cluster with istio configured. Each of the API mock service will have a unique hostname • Testers could start playing around the mock services even before the real service comes out API Spec Local mock Assign a namespace Configure ingress rule Deploy the services Remote mock
- 21. Input API Spec Tool Box 1 Tool Box 2 Tool Box 3 Tool Box n New Tool 1 New Tool 3 Tools in the future
- 22. Questions?
- 23. Thank you!
Editor's Notes
- 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.
- 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.
- 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
- 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.
- 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.
- 1. Since the api specification is both machine readable and human readable, it could be leveraged by api tools for various purpose
- 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