search

wet-boew / wet-boew-api-standards

Possible requirements for Government of Canada APIs based on the White House standards
Other
11 stars 11 forks source link

Repo approach for API standards #3

Closed pjackson28 closed 9 years ago

pjackson28 commented 10 years ago

@nschonni What do you think of the approach with this repository? The intention is to base it off of the White House API standards (which have been forked) but then to create a Canadian version from that. The initial thought is to use the fork for submitting feedback to the White House but to do the Canada-specific version (including any necessary rewrite and translation) in this repo.

The reasoning was by keeping them separate it makes it possible to submit pull requests back to the White House through the fork. Does that make sense? The downside is there is no clear relationship between the Canadian version and the White House version (since there is no direct linkage between this repo and fork).

What are you thoughts on this?

nschonni commented 10 years ago

Since the US version doesn't contain anything but a README, I'd say switch this to a Jekyll+Prose repo like the web-boew-documentation. The current structure would be better suited as a Gist.

thomasgohard commented 10 years ago

What does creating a Canadian version involve? Is it just replacing occurrences of "US" with "Canada", with the structure and content being in sync?

If that was it, and the US-version was using Jekyll, we could solve that problem using a variable. Instead of writing "US" or "Canada" you'd simply write {{ site.org_name }} and let Jekyll put the right string in.

chrismajewski commented 10 years ago

Since we start with a translation we'll likely never be able to go back into the american document.

What we can do is work in ours and create english only pull requests into the american one for select changes.

As for the Canadian version, we'll make choices and modify. I'd like to better define the metadata, they mention it offhand in pagination but I'd like to be explicit in the "metadata: {}" property and how it's used. There are other things around error handling we didn't like.

We will also need to talk about english and french data. Either your dataset includes both or you have to specify a language and offer one without a default. And, although we don't bring the topic up, we'll eventually have exemptions to that rule. Les exceptions font partie de la langue française.