Deployments independent of API descriptions

[lornajane]

I realise the deployments is the one accepted thing already in the repository, but I have feedback about it anyway.

Deployments are implementations, they're not part of the API, they're instances of the APIs. When earlier OpenAPI versions were created, it probably was common for an API to be deployed in one place. That seems less true now with microservices, preview deployments and the modern world of APIs-as-cattle. I also note that one of the most disabled linting rules I see is the one about requiring servers to be set, and it's because users declare and describe the interface - and they don't want to update the document every time there's a new rollout.

I like the idea of deployment listings - but I don't think they belong in the same description as the API shape and behaviour.

[handrews]

@lornajane I'd like to understand your concerns about the deployments proposal in more detail. I'm not advocating a position here, so hopefully the questions come across as neutral.

It seems to me that the proposal:

• Allows creating a shapes-only document with no connection to deployments (this seems to align with your thoughts - is that correct?)
• Allows creating a deployments document that only connects to shapes through the imported value in the paths field in each deployment (would this also meet your "not in the same file" criteria, or do you not even want the imported connections?)
• Allows putting both in the same file, with an implicit or explicit connection (this part does contradict what you are saying, although it looks like you cannot embed the paths in the deployment object so there is some separation)
• Based on the diagram, it looks like deployments can also be embedded in or linked from requests (this would contradict as well, especially if deployments can be embedded)

I've never really understood using servers under a Path Item or Operation, so my lack of understanding carries over to deployments under Moonwalk requests. It feels a bit design-smelly to me. Is this part of your concern?

If we kept the proposal except for allowing deployments in what's otherwise a shapes file (both at the root and under requests), would that work, or are you looking for an even stronger separation? Perhaps even two different specs?

[lornajane]

It feels very tangled. The move from basepath to servers is still confusing to users today (admittedly this is anecdata, but I do spend quite a bit of time with users of OpenAPI 3.x). Having document that is some sort of registry of deployments seems useful for quite a few use cases - but orthogonal to the purpose of describing the API . And security is sort of in the mix here, but it looks like we're attaching security to deployments, rather than to operations, so I'm not sure how that's going to work in the real world. Having a deployment document that uses imports is great, but even that has some paths (paths? operations?) which relate to a whole imported document. Should we have been referring to the paths within what I assume is an API description document, or does the document have to contain only the paths (do we even use paths now?) so it can be used from this deployments context? I think deployments might be something to revisit to complete the story once we know what the rest of the shape-only API description looks like, it does serve some use cases for sure, but leading with it feels like a stumble.

[handrews]

Thanks, @lornajane , this clarifies things a lot. If we're going to have a modular specification with clean separation of concerns, we need to define the interfaces between the modules precisely. Along with you general feel for the order in which things should be done, I think you're calling attention to the lack of clarity in the interface. I see the following things needing to be defined (whether we do deployments first, last, or anywhere in-between):

Are deployments and shapes separate document formats or do they share a format?

The current proposal uses the same format for shapes, deployments, and components. It's just that you can leave any of those out. But the first example shows inline shape definitions and uses the self key to indicate that in the deployment section. This would seem to be one aspect of the entanglement you mention - do we want to require them to be separate documents in separate formats? (I have no personal opinion on this, shocking as that may seem.)

How do you connect a deployment with the API's shape?

Currently this is done with apiPaths which takes a namespace as a value, indicating that whatever shapes that entire imported document defines, that is what is deployed. I think your questions about whether we'd even still want to reference "paths" here is an excellent one.

I also think if we just replace apiPaths with apiShape and continue with an imported namespace as a value, then this one is easy to solve. Doing this leaves us free to define whatever format and behavior we want in the shapes document, whether it is the same format or a different one. (If it's different, then you'd never set the shapes to self, but otherwise everything behaves the same).

I feel strongly that deployments must not be allowed to slice bits and pieces out of a shape. If you can't deploy the whole shape as defined by that document (and its imports), then you need to refactor. Splicing little bits and pieces all over is one of the main reasons why referencing is such a poorly-supported mess now. Let's not repeat that mistake.

I guess it might be that the ability to defines Server Objects at different path/operation levels is related to this? If so, then we need to understand what's going on there and what it should look like in a world of separate deployments and shapes. That night complicate the interface and you're right that we shouldn't rush past such things.

We will be allowing various ways of organizing components, so creating the right shape to deploy should not be difficult, and should not impact the deployment syntax at all.

How is security attached to everything?

This part is not clear to me from the proposal (@darrelmiller was there more discussion on this that didn't make it back to the proposal?) The security fields in the proposal look like kind of a combination of Security Scheme and Security Requirement Objects, but I don't understand this area well at all.

My completely-untethered-to-reality thoughts here are that a shape would have something like security requirements attached to things - operations, signatures, endpoints, whatever granularity we decide we need. The deployment format really shouldn't care. It should set up what's available for that deployment, and needs to offer the things that the shape requires. If it does not, then trying to use the shape and deployment together would be an error.

Of course I have no idea if that even makes sense, I just included it because you get more comments by proposing something wrong than by asking for opinions :-)

---

We need to define all these interfaces, and make sure they are complete. I think if we do it right it will not matter much what the internals of the shape format look like. But we need to be sure of that. If we can't be certain that we've got the interface right, then yes, I would agree with you that we need to wait to publish any sort of deployment format until we've gotten that sorted.