Clarification on the purpose of the API license?

[harrisj]

In the Swagger 2.0 specification, there is support for adding a License as one of the informational fields and the description for this is License information for the exposed API.

This seems a bit ambiguous, since a license could potentially be understood to apply to one or more of the following contexts:

1. Use of the API. This situation seems to be already handled by the termsOfService section though.
2. Data retrieved from the API
3. The specification JSON/YAML for the API indeed, there is a license for the Swagger 2 specification
4. Client/server code generated via swagger-codegen could some licenses theoretically extend to that?

I am guessing that the item 3 is the intended use for the license field, but I will admit that at first I thought it was meant for the first case and I could not see how a license would actually apply. Is it possible to get some clarification of how licenses should be picked here and where they do and do not apply?

[MikeRalphson]

I think the key word here is exposed.

1. Correct, covered by termsOfService
2. If covered at all this would also be via the termsOfService
3. My reading of the specification is that the license covers the entire design of the exposed API, so it would also include any features not included in the OpenAPI document [1]
4. In this case, generally not. Code generated by swagger-codegen is covered by the following clause:

When code is generated from this project, it shall be considered AS IS and owned by the user of the software. There are no warranties--expressed or implied--for generated code. You can do what you wish with it, and once generated, the code is your responsibility and subject to the licensing terms that you deem appropriate. [2] [3]

The license effectively tells you if/how you could re-implement and/or relicense the exposed API design.

[1] a PR to improve the clarity of the wording may be beneficial
[2] Other codegen projects will have their own licensing rules
[3] I suppose a custom license could attempt to forbid the use or distribution of generated code, but whether that would be enforceable is another matter

[MikeRalphson]

Closing due to inactivity - but please feel free to reopen the issue if necessary.

[adulau]

I would like to reopen this because it's still very unclear in the specification of what is exactly the license coverage:

• The data exposed via the API
• The API design (which I doubt as this is clearly not original enough to be covered by copyright)
• The back-end software of the API

Is there an archive somewhere where the license field has been added and the reasoning behind?

[StephanBijzitter]

I second this question. I'm creating a definition for an internal api that third parties (customers of ours) can get access to to manage their accounts/information. The code itself is never exposed; only the swagger .json file is loaded and that's really it. What's a license got to do with that?

[frankreno]

Agree with the above comments on this issue. The current definition of license in the docs is too vague and does not offer what it should be about. This issue should be reopened to be looked at to make the documentation more explicit and concrete on the purpose of this field.

[darrelmiller]

The license effectively tells you if/how you could re-implement and/or relicense the exposed API design.
I agree with Mike's comment regarding the intent of the license. The API description is a creative artifact that is not all that different to source code.

There seems to be support for clarifying the wording in the specification, so let's find some text that folks are comfortable with. Would the following addition be sufficient?

4.8.4 License Object §
License information for the exposed API. The referenced license defines acceptable usage of the API description.

[IMSoP]

4.8.4 License Object §
License information for the exposed API. The referenced license defines acceptable usage of the API description.

This feels almost contradictory to me - the first sentence says it's for "the API", the second is for "the API description". Do you need the first sentence at all if you have the second?

[miqui]

Let me take a stab at this:
info.license is intended to clarify the legal framework under which the API can be used, modified, and distributed. AND can we not agree that the API depends on (is built from) the API description ?

(Again, I am only considering the APIs originating (in any way) from an OAD.) <-----

So, if for some reason you intend for your API to be "used, modified, and distributed" as per the license type (i.e. MIT for example) and if we can accept the API's coupling to its OAD, then perhaps the license constraints apply to both the API and the OAD.

Many commercial APIs (i.e. you pay to use the product, service, etc, and do not have access to the API's source and any other implementation detail outside of what is intended) do not seem to include info.license. At least I have not found any. So, in many cases this is left out. The usage of the API itself falls under the terms of (by the company/provider) use which could include the distribution of the API's OAD presumably for the purpose of onboarding, etc).

Another point: Partner APIs. By their very nature these APIs are governed by the terms stipulated by all partners involved. Would they include a license? Not likely.

Private APIs: All aspects of the API is already owned by the company/org. Why bother with a license?

[IMSoP]

@miqui I'm not really clear what it means to "distribute an API". An API is, by definition, an interface, not an implementation.

The actions I can think of that might be restricted by copyright, and therefore releasable under a license, are:

1. Re-publishing the API Description, on a different platform, or in a different format.
2. Developing (and distributing) a client based on the API Description, for connecting to servers that expose the described API.
3. Implementing a server based on the API Description, so that your server can be used with existing clients. (For example, many storage services emulate the API of Amazon S3.)

(Remember that a copyright license grants permissions that someone would not otherwise have; it is meaningless if they already have those permissions. It's possible that "license" could refer to something other than copyright, such as "acceptable usage"; but in that case, a different field such as "policy_url" would probably be more appropriate.)

[darrelmiller]

@IMSoP I'm fine with removing the first part.

I agree with 1. I think this is what the license is for.
I'm not sure what is the point of publishing an API description if you are going to restrict 2. If you don't want to let people generate clients or documentation then don't publish your API description. That would be like publishing a document and saying that you can't read it.
I think 3 is probably the most controversial one and the essence of the Google vs Oracle case. Someone doesn't really need to have the API description in order to clone an API, so I think it is an independent issue. Having said that, I suspect that if someone has an API description and has a very restrictive license on it, then the lawyers would probably use that in defense of item 3.

Caveat: IANAL

[miqui]

@miqui I'm not really clear what it means to "distribute an API". An API is, by definition, an interface, not an implementation.

The actions I can think of that might be restricted by copyright, and therefore releasable under a license, are:

1. Re-publishing the API Description, on a different platform, or in a different format.
2. Developing (and distributing) a client based on the API Description, for connecting to servers that expose the described API.
3. Implementing a server based on the API Description, so that your server can be used with existing clients. (For example, many storage services emulate the API of Amazon S3.)

(Remember that a copyright license grants permissions that someone would not otherwise have; it is meaningless if they already have those permissions. It's possible that "license" could refer to something other than copyright, such as "acceptable usage"; but in that case, a different field such as "policy_url" would probably be more appropriate.)

Hi @IMSoP I was trying to borrow the constraints language as described in the MIT license for example. Under MIT you can distribute, etc..etc. Perhaps, the term distribution confuses things. Although making an interface available is that not form of distribution?

(Remember that a copyright license grants permissions that someone would not otherwise have; it is meaningless if they already have those permissions. It's possible that "license" could refer to something other than copyright, such as "acceptable usage"; but in that case, a different field such as "policy_url" would probably be more appropriate.)

Agree with you 100%.

[miqui]

I am leaning ONLY towards point 1 and I'll leave it at that. The last thing I want is to get blamed for re-igniting a legal case.

@darrelmiller I recommend we close this issue as unresolved UNLESS we remove the first part of your original proposal and go with the 2nd sentence.

note: comments are my own.

[ralfhandl]

The consensus in this discussion seems to be

The referenced license defines acceptable usage of the API description.

However the specs state four to five times

License [...] for the [...] API.

Checking a non-representative sample of 1000+ OpenAPI files

• 700+ do not use info.license
• 200+ reference a "Terms of Use" document
• 30+ reference the Apache 2.0 license

My recommendation: don't touch, close this issue without action.

[IMSoP]

I'm not sure what is the point of publishing an API description if you are going to restrict 2. If you don't want to let people generate clients or documentation then don't publish your API description. That would be like publishing a document and saying that you can't read it.

It's exactly the same as if you publish the SDK yourself: obviously, you're intending it to be used, but as copyright holder you have control over how it can be used. Most commonly, this means requiring attribution be included if derivative works are distributed, but it could also prohibit its use in software distributed commercially, for instance. It also generally includes disclaimers of liability, which could also apply: maybe you use an OpenAPI description to generate some code and an incorrectly labelled operation leads you to delete important data.

For example, this official SDK for the MailerSend API is distributed under an MIT license; if they published an OpenAPI description for that same API, they would probably attach the same license, with the same meaning.

The more I think about it, the more certain I am that linking to a "usage policy" in a field labelled "license" is wrong; those are more often a form of contract between you and an API provider, and are in addition to the copyright license for any software you base your client on. There are also no SPDX identifiers for such contracts, so the format of the current field makes no sense for that usage.

In the MailerSend example, they have an API Use Policy which would apply even if you didn't use any of their SDKs.

---

I think it might be reasonable to clarify license as:

The referenced license defines acceptable usage of the API description, and works derived from it.

(As ever, it's up to the lawyers to argue about the line between "derived from" and "inspired by".)

Then, add a separate field for usagepolicy, so that in the MailerSend example you would have this:

license:
  name: The MIT License
  identifier: MIT
usagepolicy:
  url: https://www.mailersend.com/legal/api-use-policy

[miqui]

Usage policy is a very interesting concept. I suppose this is the same as an overall "developer policy" which I am more accustomed to.

[miqui]

The consensus in this discussion seems to be

The referenced license defines acceptable usage of the API description.

However the specs state four to five times

License [...] for the [...] API.

Checking a non-representative sample of 1000+ OpenAPI files

• 700+ do not use info.license
• 200+ reference a "Terms of Use" document
• 30+ reference the Apache 2.0 license

My recommendation: don't touch, close this issue without action.

Cool. Thanks @ralfhandl . A long time a go I was curious about this since someone in my last company asked if we should use this attribute to internal API designs. I took a quick peek at APIS.guru and similar (most if not all did not use license attribute).