web API design

[nathany]

To start we may want to research how each existing implementation (that has a URL-based API) does it.

A spec as a markdown file in this repository should provide enough detail that someone could implement the same API.

Public facing documentation on how to use the API will need to written near the end.

[espadrine]

Part of the intent of b.adge.me was to have both the ability to talk to existing badge vendors (for redirection, as we discussed with Travis-CI), and have the ability to deliver images for other badge vendors, to push for compatibility between them.

As a result, this is what delivers a badge from the text it is made of:

http://b.adge.me/:<SUBJECT>-<STATUS>-<COLOR>.svg
Use two dashes -- to have one dash as text.
Use two underscores __ to have one underscore as text.
Use an underscore _ if you want a space. Or, you know, use a space.

The : (colon) at the beginning is used to differentiate with travis-ci, coveralls, etc.

http://b.adge.me/travis/joyent/node.svg

That said, there is one issue with this design (which I mostly adopted for Buckler-like compatibility): having a dash at the start of the STATUS requires a hack, such as a Unicode U+200B ZERO WIDTH SPACE. http://b.adge.me/:bonzai-%E2%80%8B--cut---green.svg

[chadwhitacre]

The : (colon) at the beginning is used to differentiate with travis-ci, coveralls, etc.

@espadrine Can you help me understand this, and how it relates to the /-delimited URL that follows? How does the colon differentiate Travis from Coveralls? Or are you saying that it differentiates TRAVIS from COLOR and STATUS in the example?

Oh! Or are you saying that the --delimited URLs are "unresolved," so to speak? You just get the straight text with no proxying back to Travis or whatever to resolve the status of the build, etc.? And the /-delimited versions do have the resolution?

[espadrine]

@whit537

http://b.adge.me/travis/node-red/node-red.svg
http://b.adge.me/:travis/node-red/node-red.svg

One is a travis resolution, the other is a self-defined badge.

[nathany]

There are actually two completely different APIs that have been discussed.

One API is used to specify the criteria for the badge over the URL line (failed, red), etc.

This is the API that Travis CI, etc. could download badges from us and serve them up through their infrastructure, or they could redirect to from their infrastructure. #94 (comment)

Then second API, the one that img.shields.io implemented (?) is to use webhooks. A badge request goes directly to our servers, then we query the respective service to determine the output (did the build pass?). @rkh pointed out the privacy concerns around this approach when used for private repos. It may be beneficial for smaller open source consumers, such as @fjcaetano's cocoapod-badges and @kura's pypipins, as they could piggyback on our HTTPS cert and servers.

[espadrine]

The way I see those APIs' use: the colon one (with text/color input) is used for vendors to redirect to, the vendor one is used for badge users that want to display all their badges uniformly but some of their badge suppliers don't use shields.

Of course, the vendor one can be extended to things that don't have external vendors, too (such as npm download counters).

[chadwhitacre]

Whatever we do, I propose that we start our paths with a version specifier such as /v1/.

[espadrine]

@whit537 Having a version specifier without a version promise is not very useful.

Does it mean that we will always support URLs with the previous versions? In that case, we'll always need to support older URLs code anyway; we'd have this requirement without the version tag, too, why have it?

Does it mean that we will support URLs of the version before, but it is deprecated?
In that case, what kind of URL changes would force us to bump the version?
Note that a version bump would then mean:

1. Everybody must change before the next version bump.
2. Every type of URL on that version scheme will have to change, even if only one type is the cause of the version change.
3. Users must listen to deprecation information.

How would we communicate a version bump?

Also, it feels to me that part of the point of having this service is that the URL we give can be trusted not to change.

[fjcaetano]

I agree with @espadrine.

Also, I think it's important to enable scaling through the URL, either using @2x (retina) or anything else. Fixed badges, like my own, sometimes look quite weird in non-retina displays, such as the iPad mini.

I also believe it would be interesting to provide both PNG and SVG, according to the extension given at the end of the URL.

[chadwhitacre]

Picking up from #101 (comment) ...

Can you specify what the differences are between the current img.shields.io API and b.adge.me?

Let's start with a description of img.shields.io and then identify differences with b.adge.me. img.shields.io currently has paths of this form: /%first/%second.png?color=%color

• If %first is the name of a supported backend service—coveralls, gittip, travis-ci—then we perform a resolution step to produce the final text key and value, and value background color (with details varying per backend; see services.py for details).
• If %first is not the name of a backend service, we use %first and %second directly as the key/value for the badge. The color is taken from the querystring, and defaults to light gray.
• %second swallows any forward slashes in the path beyond the second forward slash, so /travis-ci/ruby/ruby.png resolves to first=travis-ci, second=ruby/ruby, and /foo/bar/baz.png resolves to first=foo, second=bar/baz.

Note for instance that http://img.shields.io/gittip/jsfiddle.png will be hard to transpose, since I am case-sensitive.

Insofar as img.shields.io special-cases some of the names in the %first namespace, I don't see case sensitivity as a bad thing there. I would expect /travis-ci/blah.png and /Travis-CI/blah.png to both resolve to the same badge. Case-insensitivity in the non-special case is considered a bug (#71).

[chadwhitacre]

Re: version number. Having a version in the path doesn't commit us to any deprecation strategy. On the other hand, it does give us flexibility in the future to change to a new path layout for reasons we cannot now foresee.

[espadrine]

Let's start with a description of img.shields.io and then identify differences with b.adge.me. img.shields.io currently has paths of this form: /%first/%second.png?color=%color

I'd like to avoid encoding needless constraints in the interface. Arbitrarily forbidding a raw badge to have its first box contain travis-ci or gittip, without a good reason for it, bothers me. I wish raw badges to be as free as possible.

If that URL interface forces the first box' text to be case-insensitive, it bothers me even more — the server logs contain a lot of requests where case is significant (eg, camel-case). Not sure why, but it is there…

Note for instance that http://img.shields.io/gittip/jsfiddle.png will be hard to transpose, since I am case-sensitive.

Insofar as img.shields.io special-cases some of the names in the %first namespace, I don't see case sensitivity as a bad thing there.

In this case, the user that Gittip knows about is "JSFiddle". Couldn't Gittip theoretically have a distinct user whose name is "jsfiddle"?

Regardless, whether Gittip itself is case-insensitive or not doesn't force us into being case-insensitive ourselves. What we receive from https://www.gittip.com/<USER>/public.json is all that counts, no matter the case-sensitivity.

Recapitulating my concerns:

1. The text in the first box cannot conflict with a supported badge vendor, and those may be added in the future, potentially _breaking bad_ges
2. Case-insensitivity breaks the promise to keep the user-provided data as intended (eg, http://img.shields.io/IcecaveStudios/ok.png?color=green gives [icecavestudios | ok])
3. You cannot have / in the first box

I would like to request a change of the main public URL API, with the promise of backwards-compatibility.

Can you give me your opinion on the current b.adge.me API?

If the request doesn't match the b.adge.me API, I'd use /%first/%second.png?color=%color as a fallback. I already have a working patch ready.

For the fallback, I need you to give me the list of all supported colors. I believe I support most (all?) of them, but this is about making sure that no badges break.

Should I automatically lower-case the text in the first box in the backwards-compatible API?

[espadrine]

Update: currently, the b.adge.me code fallbacks correctly to the older URL API.

[chadwhitacre]

In IRC we've come to this proposal:

• For "custom" badges, use http://img.shields.io/badge/foo-bar-color.svg.
• For "vendor" badges, use http://img.shields.io/foo-vendor/bar.svg

We have two alternative "custom" strategies to merge into the above.

Things to note relative to the b.adge.me "custom" strategy:

• Using /badge/ instead of /:. It is more semantic, though longer to type. It's also nicely parallel with the vendor badges: this becomes in effect another vendor.
• Keeping the filenaming semantics around -, _, . This results in a nicer filename when downloading custom badges than having path parts as with the-old strategy.

Things to note relative to the img.shields.io-old "custom" strategy:

• Moving custom badges under a namespace /cheez/whiz.png -> /badge/cheez-whiz-yellow.png
• Removes limitation on custom badges that they couldn't conflict with vendor names.
• Putting all info into the filename instead of across path parts, for nicer download names.

See #101 for transition plan.

[chadwhitacre]

Twitter poll re: /: vs. /badge/:

https://twitter.com/whit537/status/426446973088956416
https://twitter.com/espadrine/status/426450726722625537

[chadwhitacre]

Decided for /badge/! IRC

[chadwhitacre]

Thinking in IRC re: a /v1 prefix is that since this is an image API, we aren't going to be able to deprecate old URLs in the way that JSON APIs get to, and that therefore a /v1 prefix doesn't add any value.

[chadwhitacre]

@mchiodo It's nice to have it point to a filename so that if you're downloading it you get a well-named file. It occurs to me that we may well one day want to serve something besides these little badges, at which point having a new, clean namespace to play in could be advantageous. We can always carve that out of the current top-level ns though.

[chadwhitacre]

Closing. We're live with:

http://img.shields.io/badge/foo-bar-green.svg