Typescript Fetch REST API Client Libraries (Experimental)

Introduction

Hi Everybody,

For a recent Innovation week within the Ecosystem team at Atlassian, one of our teams decided to use the public Swagger/OpenAPI files that back our REST API Documentation on developer.atlassian.com to generate REST API Client Libraries in Typescript.

You can find them at:

If you have any feedback, please communicate it by making comments on this post. Please let us know if you would like us to generate client libraries for other Atlassian Products and services.

If you do use these libraries, we would love to hear your feedback in the comments.

P.S. We generated these libraries with a great amount of help from the excellent openapi-generator tool.

How to use it

Let’s let the code speak for itself:

import { ContentApi, Configuration, Content } from 'fetch-confluence';

const config: Configuration = new Configuration({
  fetchApi: yourFetchClient,
  basePath: "<your base path>"
});

const content: Content = await new ContentApi(config).getContentById({ ...args });

Some of the highlights include:

  • A fully spanning Typescript / Javascript Promise based API for select Atlassian products.
  • Types for the Request and Response objects. (This will give you autocomplete in editors/IDE’s like Visual Studio code)
  • The ability to override the fetch client used so that this library can be used in both web-browsers and web-servers.
  • The ability to override the basePath, allowing you to communicate with your-domain.atlassian.net.
  • Both CommonJS and es6 generated code, for greater portability and bundling ability.

Caveats

These libraries should be considered to be very Experimental. With that in mind, here is a minimum set of caveats to keep in mind if you decide to use these libraries:

  • There is no guarantee of correctness. Our initial testing shows that the OpenAPI generator seems to generate working methods to make REST API calls against Atlassian Products but there may be particular REST API Operations for which code has been generated incorrectly. If you find any, please raise an issue.
  • There is no guarantee of support. If there is something wrong in the library then please raise an issue. But there is no guarantee that issues will be fixed in a timely manner.
  • There is no guarantee of updates. The Atlassian Product REST APIs will change over time. Our ability to update these libraries to match the products is not guaranteed.
  • Semantic versioning is NOT used for these libraries. There is no indication of breaking changes between version bumps. This means that, if you want to make sure that the library does not contain breaking changes from one build to another, then you should pin the version of the library. That said, we have made certain choices to try and ensure minimal breaking changes between versions.

Even with these caveats, we hope that you find these libraries useful.

10 Likes