Skip to content

Home

Jump to bottom
James-S edited this page Sep 1, 2021 · 14 revisions

Welcome to the tip-initiative-apis wiki!

First, you may want to familiarize yourself with the TIP initiative and the group working on the technical aspects of it. The documentation is conveniently located here. And the charter is located here.

The next step will likely be some basic tooling and some pointers on how all of this works.

Tooling

Microsoft Visual Studio Code is an excellent text editor is all you need to alter the code in this repository, but if you want syntax highlighting and additions that make life a little easier, you may want to use an actual editor like this free tool we recommend--Visual Studio Code.

VS Code YAML extension is the VS Code extension that will give you the syntax highlighting for YAML. Syntax highlighting changes the color of the words in a document to indicate its syntactic function.

VS Code Open API (Swagger) Editor is the extension that will allow you to navigate the OAS document more easily and verify that the code is written correctly.

SourceTree is a Git GUI that can make interacting with Git a little bit easier if the command line interface (CLI) of Git is intimidating.

OAS Code Generators

  • An exhaustive list of code generating tools. These tools can create stub code to ramp-up development against TIP specifications. Below are a couple of vendor favorites.

  • NSwag · NSwag is a Swagger/OpenAPI 2.0 and 3.0 toolchain for .NET, .NET Core, Web API, ASP.NET Core, TypeScript (jQuery, AngularJS, Angular 2+, Aurelia, KnockoutJS and more) and other platforms, written in C#.

  • openapi-generator · Code generation for server stubs and client SDKs. It also provides a command line utility for validating OpenAPI syntax (openapi-generator validate). Circleci is currently running openapi-generator validate on all incoming Pull Requests, you can run these same tests locally before pushing changes.

Technical Documents

Git Flow gives you and introduction in how Git specifically works and how version control systems (VCS) work in general.

Open API Specifications 3.0 is the structure the TIP initiative follows when creating TIP API specifications.

API style follows the Microsoft API developer guidelines with a lot of the much easier to read Python Style Guide sprinkled in for good measure.

  • Use lowerCamelCase for all elements. These appear in all of the API endpoints and schemas. For single value elements, this MUST be a singular word (as opposed to pluralized - that means no "s" on the end). Array elements MUST be pluralized.
  • Use CapWords for element type definitions. These appear in the schema definitions regularly (especially Common Models) to define an object's structure. They should be singular (as opposed to pluralized) words. We use the CapWords style because it's very easy at a glance to see if you're defining an object or using it.
Clone this wiki locally