search

bcgov / api-guidelines

BC Government API Guidelines
https://developer.gov.bc.ca/Data-and-APIs/BC-Government-API-Guidelines
Other
29 stars 10 forks source link

API Centric over API First #2

Open cwevans opened 5 years ago

cwevans commented 5 years ago

Working in 'vertical slices' (API, testing, database, UI) is a keystone habit for Agile Product development. API First implies a horizontal development pattern where the API goes to a 'Backend' development team with its own Product Owner. DevOps teams in the BC Public Service are autonomous and cross-functional, working on the API layer simultaneously with all other layers.

The Government of Canada standards promote an API-Centric approach including principle 4, "Consume what you build" which states in part, "Build APIs in parallel with an internal use case".

Frontend and Backend teams introduce waiting (one of Lean's muda/wastes).

Please consider API Centric over API First.

juhewitt commented 5 years ago

I'm still learning my part of this journey as I come into the Justice Sector. From what I'm seeing so far with my colleagues, it is perceived as API Centric, but in our world, API First is the mantra that then moves down the chain based upon a hybrid integration model. @mahoneyg and team are bringing me up to speed on the pragmatism of the situation. I'll see what more I can do and learn in this space, but we actually cannot separate some integration concepts from the backend and frontend philosophy. So for us, a hybrid integration model led by API First is our choice.

jeff-card commented 5 years ago

Thank you for your comment! A peer review was held on August 9th and we have the following feedback:

We determined that this language differentiation was too nuanced for the overarching purpose of the guidelines. A consensus was reached to keep the current language.

cwevans commented 5 years ago

OK, but I may point out that this issue has the most Thumbs Up emojis out of all feedback you received if you were to reconsider.

jeff-card commented 5 years ago

This is a living document and everything is open to reconsideration. The goal of the language is to promote the API as a first class artifact rather than the traditional afterthought. There was some degree of indifference in the language of 'first' vs 'centric' (we may have somewhat misunderstood your point around front end and back end team handoffs thinking that didn't have to be the model) and the group decided that 'first' is more recognized/used in the industry.

You will see the 'consume what you build' statement (as per the fed standard) in the "API Consumption" section of the guidelines.

Happy to continue the conversation around this piece.

juhewitt commented 5 years ago

More than happy to continue the discussion. Again, we reviewed what was here on gitHub against the experts in the room. Being transparent, we Googled both terms, and found API First was overwhelming in its usage and it resonated with the group. When then went further into the it, and tried to see it from an up high lens (executive readership) to an implementation (integration team/developers who are actually the consumers here), and again in both cases API First was endorsed. When they meet again, you should attend and see what the group says with your experience and story telling.

cwevans commented 5 years ago

Thanks Jeff and Justin, perhaps I'm simply misinterpreting the term. BTW -- these are excellent guidelines, just the one term doesn't sit well with me. I'll try and make it to the next meeting if the group feels it's worthwhile discussing again.

My understanding is that API First (aka Contract First, aka API Design-First) prescribes a certain way of working where the specification/documentation must exist before a developer can write a line of code.

Many development teams in BC Gov work Code First and then generate the API spec/docs.

This article explains the difference as I understand it: https://dzone.com/articles/design-first-or-code-first-whats-the-best-approach

I believe API First would have come up frequently in search terms because it is a 'thing'. A way of working. And I'm not sure that's the intent of the term as defined in these guidelines.

juhewitt commented 5 years ago

I really like the article you shared Chris, and I think the plain language of it is even better in describing the two different approaches. So, to your point, I think we are actually getting closer to defining two separate 'things' that are related. In API First, I think what we are wanting is to convey, is an organizational integration strategy of building APIs rather than other integration methods. If you want to connect A to B, then you must use an API = API First Strategy. So in documentation, that's the language we want to convey. You got here, to these API guidelines, b/c the Province is taking an API First approach to implementing its integrations. Literally a sentence or two.

And then you to your point, I completely agree, it's two different development approaches, and as the API guidelines speak to a developer audience, we are stating guidelines as to how to build out your API as a developer. In that case, like you are stating, I'm taking API Code-First or API Design... it sounds crazy when I say it out loud, but I agree, I see what you are seeing in my experience too. I don't build swagger first, I build the API based upon business logic, get it functional, and then document after ala Swagger.

If we as a community can agree on separating the two concepts, and then state that the guidelines recommend an API Code-First mentality, I think we got it.