Platform Dev. Guide - Documentation & Client Support

The Ed-Fi ODS / API comes with several chunks of documentation and client-facing material to help platform hosts support developers of client applications.

Online API Documentation via Swagger

The REST interface to the Ed-Fi ODS / API exposes metadata based on the open source Swagger framework.¹ This metadata describes all the API resources as well as the inputs, HTTP verbs, and schema of the exposed resources. This metadata enables a user interface to automatically generate and display API documentation. This documentation describes everything a client needs to connect to the ODS / API, including resource URIs, methods (e.g., GET, POST, PUT, DELETE), parameters, and so forth.

The documentation also supports the ability to make sample calls through the UI, which means client developers can try out calls and review responses before writing a line of code. A key benefit of auto-generating the documentation is that any changes you make to the data model will automatically be reflected in your platform's client-facing documentation.

To get a sense for the appearance and content of the documentation, you can view the docs for an as-shipped version of the ODS / API hosted at https://api.ed-fi.org/v2.6.0/docs/. Also, the Using the Online Documentation section of the API Client Developers' Guide provides an overview of the documentation along with information on how to make sample API calls through the UI.

Client SDK Code Generation for C# and Java

The same metadata that the Ed-Fi ODS / API exposes for documentation also supports the ability for client-side generation of data access SDKs. The generated SDKs include client libraries and server stubs based on the resources exposed by the API. The Ed-Fi Alliance distributes sample SDK generators for C# and Java. Clients connecting to the platform can use the SDKs provided by the Alliance as a starting point – or write their own. The SDK's purpose is to automatically create code interfaces and data access objects that match the platform API exactly.

By supporting flexible, client-side SDK generation, platform hosts can provide excellent tools to support client developers – without mandating or relying on a particular kind of code or programming model. (This doesn't prevent platform hosts from distributing a preferred SDK – however, the Ed-Fi Alliance recommends supporting client-side SDK generation to ensure that your system vendors and partners can leverage work they may already have done for other Ed-Fi-based APIs.)

The Client SDK code generation is based on the Swagger Codegen tools. An excellent overview of how the Swagger Codegen works is available on the Swagger website. More specific documentation on the SDK generation for the Ed-Fi ODS / API is available in the Using Code Generation to Create an SDK section of the API Client Developers' Guide documentation.

API Client Developers' Guide

The Ed-Fi Alliance also publishes an API Client Developers' Guide that describes the fundamentals of connecting client applications to an Ed-Fi-based ODS / API. Platform hosts can refer clients to this documentation – or use the guide as a starting place for documentation describing their own platform instance. See the API Client Developers' Guide documentation for more details. 

¹ In January 2016, the Swagger specification changed its name to the OpenAPI specification. As of this release, the Swagger toolset hasn't changed its identity, and this release of the Ed-Fi ODS / API still relies on the original Swagger specification, so we're sticking with the old name for now.