Inheritance and extension of API definitions

[Julien Silland]

Hello,

My company runs an API that we surface to three distinct audiences: third party developers, partners and first party clients. What this segmentation means in practice is that depending on the nature of the clients, a given endpoint might be available to you or not, and it if is available, the response might be more or less rich.

We are just getting around to completing the Swagger specification of our public API and eager to publish that. We also have a goal to consume a Swagger spec to generate clients and documentation for partners and internal customers. For confidentiality reasons, we'd prefer keeping the internal endpoints and payloads out of the public definition.

Swagger comes out of the box with support for inheriting models and we're thinking of taking advantage of that to formalize responses returned by non-public endpoints:

{
  "InternalFoo": {
    "allOf": [
      {
        "$ref": "foo.json#/PublicFoo"
      },

      {

        "properties": {
           …

      }

    ]

  }

}

What I'm trying to see is whether we could apply the same approach for extending the public API with partner and internal endpoints — ideally, we'd keep maintaining the external Swagger spec as is and the internal one would "inherit" from it and automatically benefit from additions to it, all the while accommodating the redefinition of certain response types and the addition of certain endpoints. At a fundamental level, what I'm trying to accomplish is:

swagger-internal.json

{
  "$ref": "swagger.json",
  "paths": {
    "/foo/{id}": {
      "get": {
        "responses": {
          "200": {
            "schema": {
              "$ref": "internal-foo.json#/InternalFoo"
            }}}}}}
},

 Is such a thing supported at all by the tooling? Is there a different model we could follow to accomplish this?

Thanks,

-Julien

[Ron Ratovsky]

Hi Julien,

 

The spec doesn’t quite support that. What it does support is referencing specific paths, and then theoretically you can add additional operations on top of that to the path.

 

In practice, I’m not sure too many tools would support adding the additional operations, though the paths referencing should work.

 

Depending on how you develop and build your API, you might be able to take a different approach. You can have everything in one file, and add some vendor extensions. You can write a very minimal app that will serve the spec with some form of authorization, and filter out the internal operations based on the extensions.

--
You received this message because you are subscribed to the Google Groups "Swagger" group.
To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Julien Silland]

Thanks Ron for your answer — this is a little disappointing but good to have our intuition confirmed.

It'd be great if such use cases were supported in the future. In a perfect world, we'd version our API differently but this decision is well behind us at this point. I suspect the same is true for a number of API publishers out there. Beyond the public/private use case we are facing, implementing something along the lines of API inheritance/extension would enable fun/meaningful things:

- extend public APIs, e.g. publish an API that replicates another one and adds additional endpoints or tunes the behavior of a specific endpoint

- help with API versioning — it you could reuse large chunks of a previous version and selectively alter/deprecate certain endpoints.

On your suggestion to filter out the specification when it is served — it's an interesting approach but I'm not entirely sure how workable that will be for us: our plan includes publishing the public spec to a public Github repo. I think I might try to develop some lightweight tooling of our own to do what we want here.

Cheers,

-Julien

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggersocket+unsub...@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to a topic in the Google Groups "Swagger" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/swagger-swaggersocket/xkn9tcx8tcM/unsubscribe.
To unsubscribe from this group and all its topics, send an email to swagger-swaggersocket+unsub...@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--

Move at a regular pace and fix things

STRAVA

Stand With Us.

[Ron Ratovsky]

For any feature requests for the spec, you’re welcome to file a ticket at https://github.com/OAI/OpenAPI-Specification/.

--

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to a topic in the Google Groups "Swagger" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/swagger-swaggersocket/xkn9tcx8tcM/unsubscribe.

To unsubscribe from this group and all its topics, send an email to swagger-swaggers...@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

 

--

Move at a regular pace and fix things

STRAVA

 

Stand With Us.

--

You received this message because you are subscribed to the Google Groups "Swagger" group.

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.

[Calder Carey]

--------------------------------------------

On Tue, 8/1/17, Ron Ratovsky <r...@swagger.io> wrote:

Subject: Re: Inheritance and extension of API definitions

To: "swagger-sw...@googlegroups.com" <swagger-sw...@googlegroups.com>
Date: Tuesday, August 1, 2017, 1:40 AM

#yiv0345487967
#yiv0345487967 --

_filtered #yiv0345487967 {font-family:Arial;panose-1:2 11 6
4 2 2 2 2 2 4;}
_filtered #yiv0345487967 {panose-1:2 7 3 9 2 2 5 2 4 4;}
_filtered #yiv0345487967 {panose-1:2 4 5 3 5 4 6 3 2 4;}
_filtered #yiv0345487967 {font-family:Calibri;panose-1:2 15
5 2 2 2 4 3 2 4;}
#yiv0345487967
#yiv0345487967 p.yiv0345487967MsoNormal, #yiv0345487967
li.yiv0345487967MsoNormal, #yiv0345487967
div.yiv0345487967MsoNormal
{margin:0in;margin-bottom:.0001pt;font-size:11.0pt;}
#yiv0345487967 a:link, #yiv0345487967
span.yiv0345487967MsoHyperlink
{color:blue;text-decoration:underline;}
#yiv0345487967 a:visited, #yiv0345487967
span.yiv0345487967MsoHyperlinkFollowed
{color:purple;text-decoration:underline;}
#yiv0345487967 p
{margin-right:0in;margin-left:0in;font-size:11.0pt;}
#yiv0345487967 pre
{margin:0in;margin-bottom:.0001pt;font-size:10.0pt;}
#yiv0345487967 span.yiv0345487967HTMLPreformattedChar
{font-family:Courier;}
#yiv0345487967 span.yiv0345487967hoenzb
{}
#yiv0345487967 span.yiv0345487967EmailStyle21
{color:windowtext;}
#yiv0345487967 span.yiv0345487967msoIns
{text-decoration:underline;color:teal;}
#yiv0345487967 .yiv0345487967MsoChpDefault
{font-size:10.0pt;}
_filtered #yiv0345487967 {margin:1.0in 1.0in 1.0in 1.0in;}
#yiv0345487967 div.yiv0345487967WordSection1
{}
#yiv0345487967 For any feature requests for

 Cheers,-Julien  On Fri, Jul 28, 2017 at 6:37

ersul complet defavorabil al razboiului pentru Polonia a ingrijorat cercurile politice romanesti care pastrand o stricta neutralitate oficial au inteles totusi sa acorde acestei tari invinse un pretios aliat in perioada interbelica intreg sprijinul.