Initial list of rights

[Myron Ahn]

I'm not sure if it is premature, but maybe we can use this thread to
start brainstorming the list of "rights" for API developers

I can kick it off, based on some of the anecdotes and some of our
experiences:

- Homepage for developers with wiki
- Clear list of API representatives/maintainers
- Basic mailing lists minimum of with announce, general-discussion
- Bug tracking system with clear version numbers (combine with wiki,
assume a Sourceforge- or Trac-like system?)
- Up-to-date documentation pages with discussion on each page a la
PostgreSQL documentation, with sample code on each page
- API Documentation clearly labeled with version number of API
- Clear way to use the different supported versions of the API (i.e.
you can use API versions 1.0 and 2.0 at the same time if they are both
supported)
- SLA or guarantee that a particular version of the API will be
supported for N months after a newer version comes out
- Clear way of getting an API key or authorization
- Clear limits and guidelines on API usage, clear pricing structure
- Resolution process for API users who have been locked out, well-
defined arbitration process
- Clear and complete sample code in at least some of the supported
languages, perhaps choose a "standard" lanugage for REST interfaces
like PHP or Ruby or Python?
- "Demo" environment for testing which is refreshed to a known state
on a regular basis.

I also wonder - with these rights probably come responsibilities - and
we should probably enumerate those too, such as: developers should
always provide test code when documenting an issue, developers should
behave with civility on the list, etc.

-Myron

[mudegwah]

I would suggest brevity is key:

No apps cut off without notice or warning.
No breaking changes without new versions.
Publicly stated contact point (email/telephone/forum whatever)

To me, not having these are the things can totally screw an
implementation. It's concise, it's easy to commit to. The other stuff
is great, but very 'dev focused'. We can't expect SLAs from sites
we're not paying for, but the above is a tolerable, reasonable list,
and it's hard for a provider to argue against...

Michael.
@mudgewah
http://www.wawra.co.uk

[Neil Ellis]

On 14 May 2010, at 16:23, mudegwah wrote:

> I would suggest brevity is key:

+1

>
> No apps cut off without notice or warning.

You would need to clarify what sufficient notice is as @Aral discovered today.

I think the Apple scenario is a good example of the other situation that people fear most - an SLA change that bans your work just before you go live.

> No breaking changes without new versions.

Hard one to get agreement on - I doubt many API providers would go for that. I think fair warning again is the issue.

> Publicly stated contact point (email/telephone/forum whatever)
>

Fair enough.

[mudegwah]

An English legal idea would work here: "reasonable". I know it's wooly
but it can work. If they want to pull your app, they should tell you
before hand, with 'reasonable' notice. So not 25 minutes, but let API
providers be good netizens and if they act like dicks they lose their
certificate.

Breaking changes are sometimes inevitable, but again, reasonable
notice. Again, act badly, get burned.

As more people adopt the idea, the rules can slowly get a bit
stricter. Of course, the devrights group would have to follow these
rules too...

mudgewah

[Neil Ellis]

I appreciate the need for simple and concise so in that interest could I suggest then:

"The API supplier will make all reasonable efforts to contact the API consumer prior to removal of access rights." - The Aral Clause

This would cover @Aral's case where it seems they didn't make all reasonable efforts. Anything that would use the term reasonable should come with an example of reasonable to aid comprehension.

"The API supplier will not make changes to either the legal terms or API specification which would prohibit any reasonable use of the API or platform without sufficient warning." - The Apple Clause :-)

ATB

Neil

[mudegwah]

Awesome.

I almost want to say they could be 'snappier' but really, they'd lose
too much, so I say keep them. I like 'The Aral Clause', it is
supportive of the problem, but the Apple Clause is too accusative,
when loads of other people do it, and we don't want to single them out
at 'the top level' per se. Dunno...

Got a sappy name for the contact clause?

[Neil Ellis]

Yes you're right :-) I can't think of anything snappy now unless there is someone who publicly fell foul of it that we could use.

"The API supplier will make all reasonable efforts to contact the API consumer prior to removal of access rights." - The Aral Clause

"The API supplier will not make changes to either the legal terms or API specification which would prohibit any reasonable use of the API or platform without sufficient warning." - The 331 Clause  (after section 3.3.1 of the Apple Developer Agreement)

Anyway, all just musings .... 

[Aral Balkan]

A quick chime in (catching up on all the messages after spending today
rebranding my app and submitting new binaries to Apple) – I can't
state enough how important it is that we keep the document brief. I'm
thinking no more than half a dozen points.

The key thing is to keep it simple, and make it a no-brainer for API
providers to sign up to it. If we can distill the core, major issues
that we need addressed and have API providers sign up to them, we will
already be light years ahead of where we are today.

In addition to the core Developer Friendly certification, perhaps we
could hatch a Creative-Commons like system that shows developers, at a
glance, what they can and can't do with the API. i.e.,
Commercial/non-commerical use, API limits, etc.

Going to read the rest of the messages now :)

Aral

[Martin Pilkington]

On 14 May 2010, at 7:24 am, Myron Ahn wrote:

- Clear way to use the different supported versions of the API (i.e.
you can use API versions 1.0 and 2.0 at the same time if they are both
supported)
- SLA or guarantee that a particular version of the API will be
supported for N months after a newer version comes out

While I agree with the idea, I don't think these should be a requirement. It isn't exactly easy to do multiple versions of anything, let alone an API. What if you make major changes to your app that means the 1.0 API cannot be compatible. And what about cases where someone moves to version 3.0 and decides to remove 1.0 so they can clean up their code, even though there are a few 1.0 holdouts?

I think a much better clause would be this:

- Any APIs to be deleted should be marked in documentation as "deprecated" for a reasonable length of time before removal, giving clear details as to what APIs they should use instead.

With a possible secondary clause:

- If an incompatible change is to be made to a public API, said API should be deprecated and a new API created in its place.

This gives API developers the flexibility to keep their codebase fairly clean while giving API users time to switch their code over to new APIs.

Thanks

Martin

[Doug]

On the flip-side, has anyone seen Soundclounds Dev Manifesto?

http://soundcloud.com/developers/manifesto

Points 4, 5, 6 & 8 mainly.

[Aral Balkan]

I like this, Martin :)

[mudegwah]

Hm. Yeah. I think this is moving in the right direction. I maintain
the original three work (not cutting off, no unreasonable breaking,
and contact points) and make a good core, it's just a matter of
wording to get the specifics... Of course, what Martin suggests is
coherent with the first point of 'notice'. Perhaps the whole thing
really comes down to the API vendor giving notice before they cut off,
change, etc.

If we can boil these into 3 snappy, clear 'slogans', it'd be great. It
works on one slide, one page, etc. Really easy and clear. It gives us
a good 'constitution' to start pushing on. But as I said to Neil, the
hard part is the snappy slogan vs the practical detail. We just need
to work them into something that works without them losing their bite.
Remember, these are things that are bound to put providers out of
their way a little, we just need to get the balance right.

I admit we often have to break an old API, we migrate, we release etc,
but to do so we allow some migration time for developers - otherwise,
what's the point! If you can't version, you allow for migration...
Hence we talked about "reasonable". Maybe a big security issue means
you have to screw a load of developers, but if The Register just outed
your flaws all over the net, you've not a lot a choice! We can't
really complain about that, it's a complex game and we have to give a
fair chance when weird things happen. You can't cover all
conditions...

mjw

[Martin Pilkington]

On 15 May 2010, at 11:27 pm, mudegwah wrote:

> I admit we often have to break an old API, we migrate, we release etc,
> but to do so we allow some migration time for developers - otherwise,
> what's the point! If you can't version, you allow for migration...
> Hence we talked about "reasonable". Maybe a big security issue means
> you have to screw a load of developers, but if The Register just outed
> your flaws all over the net, you've not a lot a choice! We can't
> really complain about that, it's a complex game and we have to give a
> fair chance when weird things happen. You can't cover all
> conditions...

Maybe we need to define reasonable with an exceptional circumstances clause. Something along the lines of:

'Any mention of a "reasonable period of time" should be taken to mean, at least the amount of time you can expect an average API user to see any change, act upon that change and release an update to their software. The one exception to this would be security issues that break compatibility, where waiting for users to move over to a new API may compromise your system, in which case an immediate change followed by a clear explanatory blog post and/or mailing list post would be sufficient.'

That might be a bit wordy but it lays out an expectation of "reasonable" and shows that while users don't want to be screwed over, they accept that their app may still break if they are either too slow to update or if there is a security issue.

Thanks

Martin

[phunehehe]

Hello,

To me the idea of "reasonable" is largely subjective and that way it's
not clear at all. I'm expecting something like "1 month" or "10 days".
With a view to create a kind of qualification to API services, I think
we generally need terms that the company offering the service must
agree to comply. Now if we really state "a reasonable amount of time"
then when bad things happen, the service providers can just give
another definition of "reasonable", and the situation will be worse.

And just as Martin said, there can be exceptions, for urgent cases...

Phu,

[Martin Pilkington]

On 17 May 2010, at 4:34 pm, phunehehe wrote:

> To me the idea of "reasonable" is largely subjective and that way it's
> not clear at all. I'm expecting something like "1 month" or "10 days".
> With a view to create a kind of qualification to API services, I think
> we generally need terms that the company offering the service must
> agree to comply. Now if we really state "a reasonable amount of time"
> then when bad things happen, the service providers can just give
> another definition of "reasonable", and the situation will be worse.
>
> And just as Martin said, there can be exceptions, for urgent cases...

Well, reasonable in regular cases would probably be 3-6 months minimum. That's enough time for someone to see it, code an update and release.

Thanks

Martin

[mudegwah]

Like I said, I borrowed "reasonable" from English law. It works. It
means "reasonable in all the circumstances". If it takes Apple (for
example) 3 months to get back to your on your app, then it would be
UNreasonable to expect it changed in 24 hours. It is UNreasonable of
Facebook to pull access with no notice. It is reasonable for Facebook
to provide perhaps 48 hours notice, given Aral's case, because it is
probably a noddy fix, and their platform authentication would surely
be no longer.

If the vendor acts like a dick, they lose their "certificate" or
"membership" whatever. But this is the only practical way of getting
round the fact that integration times vary, platforms have totally
different rules, etc. So we provide this definition that reasonable is
relative to their own stated processes, and that's the end of it, they
want the badge, they accept it. Pretty much as Martin stated it above.

[Neil Ellis]

I back that up, you can tie yourself in knots specifying this exactly.

Better to use terms like reasonable and provide illustration of the
intention when using the term.

[phunehehe]

Thinking about that, I agree that the actual time varies for each
case. There may be one problem though, as ambiguity will make it hard
for us to decide who is in and who is out... That would be alright I
guess, by letting each service provider decide their own reasonable
time. May I add an item to the list of right:
- Amount of time for notice before changes must be publicly stated
and adhered to, except for critical situations
It is kind of difficult to build up a list through email like this,
how is our wiki going? (It may be up somewhere already but I can't
find it, can anyone give me a link?)