URL to the repository for the API

[LaurentGoderre]

To promote openness and collaboration we should include a link to the API source code from somewhere in the API. I'm not sure how though.

[chrismajewski]

Can you elaborate?

I'm not sure all API code will be open, I wish we could be but it may not be possible for security reasons. From a risk analysis perspective your considering exposing private information, a vulnerability or worse credentials.

A recommendation from Brian Gray is to use GitHub as the conversation hub regarding APIs. Even if we can't provide code we can have discussions in the manner you propose.

An interim recommendation, one being pursued, is to register the ca.canada github account and tie that to the Hypertext format for each API. In any and all documentation about the API ( as a recommendation in the standard ) the opportunity to discuss the API could(/should?) be forwarded to that repository even if devoid of code.

The primary difficulty with such is registering APIs and assigning permissions to the discussion forum to the appropriate resources. The first would be handled by proposed API registrations ( to be included in the standard ) through data.gc.ca, the second is a followup by the registering party to provide a github account to administer those real or ghost repositories.

Lets sort that out formally: https://github.com/wet-boew/wet-boew-api-standards/issues/15

[LaurentGoderre]

From the risk perspective, outside experts would likely say that security through obscurity is by far the weakest form of security. Further more, if someone compromises your database it doesn't really matter if the intruder has the api code at all. He could do a dump locally and figure it out.

[chrismajewski]

Closed source and obscurity are not quite the same thing, "through obscurity" implies it's a part of if not the whole defence plan. Closed source may be for multiple reasons, rarely good but often necessary ( trade secrets, architectural design limitations, NDA partnerships ).

Regardless, point well taken in light of Adobe's source code leak. We agree int the principal of being as open as possible for as long as possible but at one point you have to stop sharing. No one would want to share credentials with the public.

Agreed, compromise at the machine level defeats any security in the API. Even worse I'd worry about someone injecting code/data into the API or database to manipulate the data going out. Stealing data is one thing, stealing the authoritative voice is another mess entirely. "Government leaks ... " vs "Hackers have controlled government sites for ...". One you can survive as a single lost battle while the other is systemic failure.

I think we are on the same page in centralizing and being as open as possible. I'd like to start with documentation about APIs and the interface with the public. Open Source is an element in any discussions about design and storage/backup.

Merci encore Laurent

[samboisvert]

I strongly believe that we can't enforce this. If departments are inclined to post their source code on GitHub, more power to them, but not everybody will be on board for a variety of reasons.

[samperd]

Perhpas we can have a point system like the Open Data five stars system. This could be a five star system for open API's. Essentialy providing source code would provide one of the five stars. Perhaps something like

• Provide source code of API
• Provide Developer Documentation
• Leveraging common standards (eg ISO), Specifications (OGC)
• Accessible
• Usable
• Interoperable

more info: http://5stardata.info/

[chrismajewski]

For large optional feature sets that's a great system but we can't make any of those voluntary save the source code.

That would be a good start to validating your API. I'd add

• Crawl-able from root to all data via links