API

[jstayton]

As we look toward a future where we have multiple apps and microservices acting as a single product, I think we need to start nailing down our API conventions. We want developers to have a consistent experience, much like users will navigating through a browser.

I've been drawn to the JSON API standard. It's pretty easy to grasp, close to what we're used to, and takes the guess work out of things like how to do pagination.

What it doesn't address is how to do versioning and authentication/authorization.

On versioning, I'm a fan of specifying it in a header instead of in the URL. But there are many varying opinions. I'm open to debate.

Authentication and authorization is a bit trickier. There's everything from HTTP Basic (which Monk ID uses), to Authorization: Token (which Donate and Checkout use), to an X-AUTH-TOKEN header (which the CMS JSON API uses), to... OAuth. I don't know what the answer is here. My feeling is "root" and even account-specific access/tokens will only work for so long. For example, what if a third-party app wants to display the modules/records that a specific user has access to? I see OAuth in our future.

Finally, I think we'll want to create a central "app manager", so a developer doesn't have to register separately for all of the different components. I know there's a lot involved in that idea, but we can flesh out the details when the time comes.

I'd love to hear your feedback and questions.

@shanebonham @rickyatmonk @mcordell @kennykaye @lefthand

[rickyatmonk]

For JSON property field names, I propose we use lowerCamel case. It's ubiquitous in javascript. And since JSON is javascript object notation, we ought to abide by what is common in javascript. It's also pervasive in the airbnb javascricp guide: https://github.com/airbnb/javascript#variables

The jsonapi.org example page shows dash-notation. This is surprising to me as dashes are also rarely used. After speaking with @kennykaye , he pointed out that "-" symbols affect dot notation. Take the following for example:

var options = {
  "var-name": {
    "foo": "yay"
  }
};

// this doesn't work  (NaN)
alert(options.var-name.foo);

// this works
alert(options["var-name"].foo);

Nobody wants to parse our JSON results the second way.

[shanebonham]

You can read more about the "dasherized" debate here: json-api/json-api#341

Seems the community wasn't really in favor of making that a part of the spec, which is why it's now just a "recommendation".

I personally prefer how snake_case looks in JSON, but also don't like seeing it or using it in JavaScript since the convention is overwhelmingly camelCase.

[kennykaye]

For what it's worth, The AirBnb JS style guide recommends camelCase for naming objects and variables.

[jstayton]

Dasherized is dumb, so let's just decide here and now that we're not choosing that.

My affinity is toward snake case...

1. We already use that for our non-PHP APIs. It's the Rails default.
2. Most of the third-party APIs I've worked with use snake case, i.e. Stripe.
3. Stylistically, I think it's prettier and easier to read than camel case. There's an interesting article on this debate on HN this morning.

That said, I do agree that camel case is mainly preferred in JS, and also the recommendation of the style guide we follow. I get lots of stupid warnings from JSHint/JSCS when I'm working with snake case JSON payloads. It's a pain. So... I'm not completely against camel case.

[shanebonham]

I agree with everything you said above, which I realize doesn't help much. FWIW, I consider JSON's relationship to JS to be an implementation detail. That is, while I am happy to use camelCase in JS, I don't find it a compelling reason to also require it in our JSON.

I have a more visceral reaction against seeing camelCase in my ruby than seeing snake_case in my JavaScript, though.

[rickyatmonk]

I too am in agreement with what's been said. Personally, I like the way snake_case conveys info (e.g my_db vs myDb)(and this is the most important thing IMO) but I like everything else about camelCase (namely its popularity, jscs support, and typability, raw aesthetic).

I'd like to get started re-factoring the JSON API to use one or the other. At this point, I'm thinking snake_case is the direction we're going so I'll plan on that. I'll work on some other stuff first to hopefully give time for @kennykaye and @mcordell to weigh in.

[rickyatmonk]

I want feedback concerning the best way API consumers can use pagination in their requests. Using http://jsonapi.org/format/#fetching-pagination as starting point... I took the "offset" approach. The consumer provides an "offset" and a "limit". A popular alternative to that is "page" and "size". The website also mentions the "cursor" method but that seems more appropriate for real-time or fast adding data (e.g. twitter or facebook feeds).

Which tactic do you think is best?

[shanebonham]

[rickyatmonk]

👍

[rickyatmonk]

I've done some research:
mailchimp, instagram, twitter, yelp, bitly all use snake case.

Oddly enough google and facebook are inconsistent between their APIs and even within them:

There were some camel cases but apparently it's not as prevalent as I thought.

For URLs does anyone have feeling about the casing of the API endpoint?

Some common options are:

/api/v1/blog-posts : mailchimp, instagram

/api/v1/blog_posts : twitter, yelp, bitly

Underscored URLs do seem weird but at least we'd be consistent with JSON field keys if we went that route.

[jstayton]

@rickyatmonk Is it hard to support both pagination methods? What if someone uses offset and size?

👍 Snake case JSON.
👍 Dashed URLs.

[rickyatmonk]

The way I implemented the dual support is to look specifically for "page" AND "size". If either of them is missing, the code falls back to "offset" and "limit". It will look for those properties. If either is missing, the default for the missing item will be used.

[jstayton]

Would you want to use limit by itself? Like to get the first 200 records?

[rickyatmonk]

If limit is the only thing provided, then default offset (0) will be used. Basically, 'limit' and 'offset' are always used and they have defaults if values are omitted or "bad". If "page" AND "size" are found together then they are converted to "offset" and "limit" behind the scenes.

[jstayton]

With that settled, any strong opinions on how versioning is done?

Authorization is much clearer to me now after looking into OAuth: we'll use Authorization: Bearer to pass the access token. Here's the standard.