https://platformengineering.org logo
#platform-blueprints
Title
# platform-blueprints
l

Leonardo Romanato

02/14/2023, 10:28 PM
Hi! I was wondering if someone here built an IDP relying on API as the way for their users to consume services and capabilities provided by the platform. I’ve heard about the API first approach a lot but, at least in my scenario, it’s hard to think it could be the way to go. A developer that want a service I would say is more keen to come to a self service portal and interact with it to have the resources provisioned rather than code the interaction with the platform: I don’t see a use case where coding that approach could make sense and to be honest, I would say if we have a scenario worth to code, it would be for the platform to code it and make it available as an E2E use case. I see the API approach some useful for AWS, Azure or a cloud provider in general, but not sure for an Internal Developer Platform. Happy to year your feedback and also your scenario if you built an API based platform.
j

Jordan Kaye

02/14/2023, 11:56 PM
What do you think developers would do with the provisioned resources? Apis are the foundation of a useful development platform. It's how the developers interact with the functionality exposed by the platform. Note that the api need not necessarily interact with a remote resource, in case that's an area of confusion
l

Leonardo Romanato

02/14/2023, 11:58 PM
I mean.. just as an example: let me say one of the provisioned resource is Jenkins project with standard pipeline.. where the API interaction would be useful here?
j

Jordan Kaye

02/15/2023, 12:04 AM
With that example the definition is a bit of a stretch, but the Jenkins project is going to have some requirements on the Repository- scripts it expects to exist or tools that it will invoke. These are the "apis" that the developers write against to make the Jenkins project useful
The same will be true of each piece of functionality the platform exposes. There has to be a way to use it or hook into it. Usually much of this will be library-level code that standardizes on functionality like logging, messaging, etc. Which of course are all accessed through their apis
l

Leonardo Romanato

02/15/2023, 12:11 AM
Thanks Jordan. All of this make sense to have tools / capabilities interacting one with the other but still I don’t see where such APIs are useful to be exposed to platform’s customers directly
c

Clemens Jütte

02/15/2023, 12:33 AM
Simple concepts make developers stick to APIs. Repeatability. Single source of truth. Fit with their current toolchain and style of work. Suppose you establish the platform interaction on an API or “as code” level. In that case, a developer ever only needs to look into the VCS and read the configuration stored directly with the code he is working on to understand what is happening. If you think about large setups, the scale factors of standardization, better assignability of developers to changing projects and the like will catch up pretty soon as well. From the top of my mind - not a complete list of concerns obviously…
j

Jordan Kaye

02/15/2023, 12:35 AM
I think I'm misunderstanding you, because I am unaware of any other (reasonable) ways to expose anything to the platform's customers
What are the alternatives you have in mind for consumption of the platform?
c

Clemens Jütte

02/15/2023, 12:38 AM
Usually configuration code falls into that category. So I have to invoke “it depends” on you - because it actually depends on what the functionality is that you want to drive. To stay in your Jenkins example - you would drop the configuration code for that “pipeline as code” into the source code repo and let the developer work on that.
j

Jordan Kaye

02/15/2023, 12:41 AM
Thanks, for something like Jenkins I think that makes sense (though I'd argue something like that runs the risk of restraining users too much - but sometimes that can be a good thing). But what about the other bulk of what you'd expect from an IDP? If no code can reach it at all (which no apis implies) I can't imagine it being a platform I'd want to be writing against.
c

Clemens Jütte

02/15/2023, 12:47 AM
Please provide a concrete example and I will try to wrap my head around it. Currently nothing jumps my mind that would be “no code can reach it at all”.
j

Jordan Kaye

02/15/2023, 12:57 AM
If code can reach it, you're calling an api
Perhaps an issue of definitions?
c

Clemens Jütte

02/15/2023, 1:09 AM
Heh… it’s late (or early? 😄 here already). I totally miss-read your last sentence
Copy code
If no code can reach it at all (which no apis implies) I can't imagine it being a platform I'd want to be writing against.
and I can heartily agree with it. If it has no API, it is most probably something that neither developers nor I would like to be part of a platform that they use for their day-to-day work.
j

Jordan Kaye

02/15/2023, 1:16 AM
Ha, I was wondering if I was missing something obvious!
l

Leonardo Romanato

02/15/2023, 3:18 AM
Well… I think I can understand your point of view but possibly I am a bit biased from the current scenario I am in. Let me say.. developers need to start a new project: they need a repo, they need a jenkins project, they need a Grafana tenant… well, as per the scenario I am in today I hardly see the team asking for this through API / code, instead they would like to rely on a visual approach (self-service catalog?) also because some of those requests will require a validation on the back of the process before to ignite the provisioning part. Is that just a matter of cultural change / mindset or am I missing something?
j

Jordan Kaye

02/15/2023, 4:28 AM
I think the difference is that you seem to be focused on the first 5% (made up number) of what I would think of an IDP as providing. All of the hard/interesting aspects of the platform happen after the initial setup. I'm not convinced an API to create a repo is useful, but I wasn't really thinking of that as part of the platform with my original statements. I do think that it is now that you say it like that, but if that's all that's being provided, I don't necessarily think I would call that a development platform. I'd call it a scaffold or something
c

Clemens Jütte

02/15/2023, 9:04 AM
@Leonardo Romanato, you’re focusing on the creation flow of a new project. This usually doesn’t happen too often and the lifetime of a project is where the bacon is. A self-service portal is in essence for this just a nice JS-driven button to execute the setup script. After that, the developers need to actively engage with the content of the repo that was created on a daily basis. To stay on the Jenkins example -you create that instance using an automated setup script. After that the platform team can totally care for all of the maintenance and operations of that Jenkins instance (and all of them) because developers don’t really care as long as Jenkins is executing their pipelines. To facilitate this separation of concerns, you put the pipeline as code in the repo. If the UI of Jenkins is the only way for the developer to interact with Jenkins and the storage of the relevant data is in that Jenkins, things start to get complicated. Maintenance windows become stop-the-world events. Backups become life savers because it is not about “Jenkins as a service” anymore but about “this specific Jenkins instance that has my pipeline data”. #insert a myriad of other concerns here# You could state that any system that is not API driven and can externalize its configuration is adding to the dependencies of the roles “developer” and “platform engineer” and, by that nature, making the collaboration more complex.
Oh… and I counter your “visual approach” with “write your own CLI for that”. That is way quicker and more efficient than actually maintaining a self-service portal, if you don’t buy something opinionated off the shelf.
l

Leonardo Romanato

02/15/2023, 1:28 PM
Ok, now it make sense! Thanks for thee useful suggestions. As you said, I think I was too focused on a specific part of the process
c

Clayton Hynfield

02/15/2023, 4:07 PM
Great question! I helped to build an internal developer platform at a large insurance company several years ago, and we did indeed take the API-first approach. I believe our reasoning went something like, "We know we need to provide some core capabilities and iterate on them, and it's going to be easier to do that by starting simply with an API and early adopters." We eventually developed a really nice web portal, but not before one of our platform-consuming lines of business wrote their own portal, encompassing many of their LOB-specific developer workflow concerns
a

Abby Bangser

02/16/2023, 10:33 AM
Big agrees that an API is not about how users will consume things, it is about how to build a versioned, evolveable, set of features. An API can (and likely will) end up with a number of UIs in front. I am seeing a lot of Backstage (or maybe Atlassian Compass) for the GUI you seem to be interested in, I am also seeing a lot of in house CLI tools and chat bots. Depends on the users!
If it is helpful, I talked about API first in a talk last week:

https://youtu.be/AUyq-Ns5dUo?t=3477

Though tbf, this talk didn’t go into the UI side of things, but maybe I can add that to the next iteration of the talk!
76 Views