API registration process/information in the API standard

[chrismajewski]

@dyomides

Could you please supply text regarding API registration for the standard

I would be keenly interested in the following being included:

• registration of the relevant Hypertext formats as described in the standard
• github accounts for administration rights to a central ca.canada repository
• confirmation that documentation exists as described in the standard for the supplied and previous versions

[dyomides]

On the first point I assume you mean registering an organization api into the Open Government portal as well as the possibility of registering datasets as api calls in order to limit the need for organizations to update the portal on a regular basis?

Registering datasets as api calls while appealing does present some contentious issues such as offering the format through a query parameter rather than the accept header or more importantly the need for a way for apis to provide a bulk download of the data ignoring limits, this will be important for data that is quite large. That being said the idea would be that an organization could register their datasets on the OG portal as api calls thus removing the need to update the dataset on a continuous basis.

The registration of an api in the portal will be documented in a separate document (Data Inclusion Guide) but in summary an organization will be required to create an api documentation web page preferably using the template that will be developed under the ca.canada organization in order to centrally house all api documentation for several reasons:

• Centrally housing all api documentation will allow developers to more easily browse through all availalble GoC api documentation and encourage cross discovery;
• Will encourage a open dialog between the api users/developers and the organization responsible for maintaining and updating the api through the issues github functionality;
• Will allow for public contributions via pull requests to documentation and possibly even the api if the organization chooses to house its api code in github as well; and
• Will provide for a uniform approach to all api documentation where the structure and the contents will be consistent from one organization to another.

The latter approach brings us to your second bullet and that is the administration of rights in the central repository. Further work on the central repository is required before documentation can be drafted but the basic idea would be that TBS would maintain control of the central repository and grant appropriate rights to each organization so that they can manage their shadow sections independantly.

On the last point I'm not quite sure I understand and will need some clarification ;)

[samperd]

Do we have a place to register GOC API's and service end points?

If we do please post link.

If we don't why not start with a separate issue where people can start documenting all the API end points?

Each entry can be formatted in such a way that we slowly build what required fields and info we want to add.

Sorry if I am late to the conversation on this one.

[dyomides]

Endpoints should be detailed on a api documentation page as described above and that page should be registered in the portal through the registry as a resource (API) with the dataset metadata record pertinent to your api. We contemplated allowing the individual registration of apis in the dataset metadata record but felt there would be a lot of overhead should the URI's change often. The documentation page is free to change as needed over time without ever needing to update the portal resource entry.. so long as that page URI doesn't change.

[chrismajewski]

We still believe a central endpoint for documentation is a great idea but we've not gotten there yet. Left open as something to better answer.

[samperd]

How about requiring self documenting and human browsable api'?

[chrismajewski]

There is a process for registering APIs in the open.canada.ca portal.

Self documenting would be great and noted but this issue can close.