DEVX-1608 - Move the API guidelines into DevHub

[MonicaG]

This PR is to take the content from the government-of-british-columbia-api-guidelines.md and place it into DevHub.

This content is currently served at https://classic.developer.gov.bc.ca/BC-Government-API-Guidelines, but we wish to retire classic.

The following changes were made from the original content:

• Removed the link at the top of the page that stated "NOTE: This is a living document, posted here for your feedback". Backstage provides links for viewing the source and opening issues/pull requests
• Modified heading tags so they would be picked up by techdocs 'on this page' feature. This means there can only be one heading 1 tag (# BC Government API Guidelines). All other headers that were using heading 1 tag were converted to heading 2 tag (## API Design, ## API Security etc). Level 2 tags were converted to heading 3 tag (### Design Principles and ### Design Patterns)
• Updated broken links as per commit 22fb93a
  • Note: The link to https://developer.gov.bc.ca/Developer-Tools/API-Gateway-(powered-by-Kong-CE) originally displayed the content from this file into the old DevHub.

Preview content here.

Redirects of the classic page are handled in PR bcgov/developer-portal#182

[rustyjux]

These guidelines have lacked ownership or updates for several years, and thus are not entirely accurate. In any case, good to be migrating them over.

I've made a suggestion re: API documentation and would also suggest changing all the headings to simply Design, Security, etc. instead of API Design.

I believe these guidelines are currently under review, however it is not by the APS team (or even the BC Data Service) - @gjlawran, correct? It might be worth touching base with whoever owns that project.

Also, perhaps a link to https://github.com/bcgov/api-guidelines is needed, if this is still a living repo providing distinct value (e.g. the pubcode.yml file). Or perhaps it should be retired. @jeff-card

@ssulehri-gov-bc-ca FYI

[rustyjux]

This is no longer true and since it is phrased as a must do (rather than most of the other guidelines which are just that), I'd remove this entirely.

Instead, API providers should be suggested to list their APIs on the API Directory, if their API may be accessed by third parties outside the organization (e.g. team or branch) that created them. Docs for sharing APIs on the API Directory - https://developer.gov.bc.ca/docs/default/component/aps-infra-platform-docs/how-to/api-discovery/

@adodge-bcg - agreed? Feel free to tag in anyone on the Data Discovery team.

[MonicaG]

Hi @rustyjux - I've updated the following based on your comments above:

• removed API from all heading sections. So, API Design is now Design etc.
• I've updated the first part of the Documentation section based on your above comments. Please let me know if it looks ok now

You can see the changes in this commit

Outstanding:

• I didn't know where to put the link to the https://github.com/bcgov/api-guidelines repo. Please suggest where in the docs it should go.

[rustyjux]

I made a couple additional changes but looks good to go after that.

Re: https://github.com/bcgov/api-guidelines, I don't think we need to reference that on this page, but I do think the managers of the API guidelines (who? @jeff-card ?) need to decide what is the source of truth - ie is it this content now in bcgov/bcdg or is it bcgov/api-guidelines.

To my eyes, the API guidelines fit right in the BC Developers' Guide (bcdg) and api-guidelines can be archived.

[jeff-card]

I think they fit in the BCDG as well, as either a cross reference or as the authoritative source. I'm fairly confident this repo is widely referenced in documentation, wikis, guides throughout our landscape.

[MonicaG]

@rustyjux - I've committed your changes and the updates are available on the preview site.

@jeff-card - Sorry, I don't think I understand. Do you want the https://github.com/bcgov/api-guidelines repo linked somewhere in this guidelines page?

I will merge this PR after interregnum period is over.