These are chat archives for APIs-guru/api-models

2nd
Jul 2015
Ivan Goncharov
@IvanGoncharov
Jul 02 2015 15:31
@bobby-brennan Things to consider. I think you need to put some disclaimer like this https://github.com/raml-apis/Uber/blob/staging/portal/api/api.md#please-note
Bobby Brennan
@bobby-brennan
Jul 02 2015 15:31
Hey, looks like some APIs made it into apilist.json without being added to the repo
e.g. clarify.io
Ivan Goncharov
@IvanGoncharov
Jul 02 2015 15:32
My mistake
I will add apilist.json update into script
to not forget it in the future
Bobby Brennan
@bobby-brennan
Jul 02 2015 15:33
it's actually in apilist, but there's no swagger for it in the repo
You can add notes to swagger.info[x-lucy/readme] or swagger.info.description and it'll show up in the readme
Ivan Goncharov
@IvanGoncharov
Jul 02 2015 15:35
I fixed apilist.json
Bobby Brennan
@bobby-brennan
Jul 02 2015 15:38
awesome thanks
Ivan Goncharov
@IvanGoncharov
Jul 02 2015 15:38

You can add notes to swagger.info[x-lucy/readme] or swagger.info.description and it'll show up in the readme

I mean only bottom disclaimer part:

Please note:
This portal and its contents are not affiliated with Uber. They are, however, useful for working with, and learning about, the Uber API.
The official developer API portal for Uber is: https://developer.uber.com/
I can't put words like 'portal' inside Swagger file
Because it's limiting usage scenarios
If it for example used in Postman in that case it became Application
Also I don't want to put it in some general field
I my mind it should be at the bottom of the page, mainly for legal resons
Bobby Brennan
@bobby-brennan
Jul 02 2015 15:55
it might make sense to have a "legalDisclaimers" field
Ivan Goncharov
@IvanGoncharov
Jul 02 2015 15:56
I think it's too usage dependent.
For example I can partner with Uber
that doesn't mean that you also partnered
or wise versa
it too usage dependant. Some portal could say "for education reason"
It's depend on legal system of the country that you are hosting in
I will definitely put general disclaimer in Readme file
But I don't see a value to put autogenerated string
which is highly context dependant into Swagger documents
It's like I'm promising someone that this disclaimer is official
Ivan Goncharov
@IvanGoncharov
Jul 02 2015 16:01
or universal.
For example someone could think about using it for commercial purposes
Bobby Brennan
@bobby-brennan
Jul 02 2015 16:09
Oh you mean I should put the same disclaimer on every API?
that works
Ivan Goncharov
@IvanGoncharov
Jul 02 2015 16:09
Yes because you kinda use trade mark
So one disclaimer per trade mark
And to be bulletproof maybe add something like this
If you are the owner of API and don't want to share your API please send an email to: legal@any-api.com
I will put similar thing at the repo
just more generic for all API at once.
Bobby Brennan
@bobby-brennan
Jul 02 2015 16:26
yeah that makes sense. I'll run everything past our lawyer as well
Ivan Goncharov
@IvanGoncharov
Jul 02 2015 16:34
in my brain it's purely theoretical problem
but consequences could be too dramatical
:(
Bobby Brennan
@bobby-brennan
Jul 02 2015 17:17
yeah I agree. I think as long as we take down or edit APIs that we're asked to I think we're OK