Skip to content

Swagger documentation for Currencycloud API v2

Notifications You must be signed in to change notification settings

CurrencyCloud/currencycloud-swagger

Repository files navigation

Currencycloud API Documentation

Source files for the Currencycloud API Documentation.

The Currencycloud API documentation is maintained in two document formats:

  • Markdown
  • OpenAPI Specification (v2) written in YAML

There are three categories of documentation on our developer centre: getting started guides, integration guides and API reference documentation. The getting started guides can be found at data/local/pages/getting-started, the integration guides can be found at data/local/pages/integration-guides and the OpenApi specification for the API reference docs is at data/local/swagger.

Most of the source documentation is written in Markdown. The only exception is the file reference.yaml, which is a YAML file that conforms to the OpenAPI Specification (OAS) v2, a popular API definition language previously known as "Swagger".

The OpenAPI definition file describes individual endpoints in the Currencycloud API. OpenAPI definitions can be written in JSON or YAML. We've chosen YAML as it is the most readable of the two formats.

All source files are UTF-8 encoded with Unix line-endings (LF, \n). They can be edited with any good text editor program. However, it is recommended to use Swagger Editor to make changes to ./src/reference.yaml. As you type, Swagger Editor will validate the document against the OpenAPI v2 specification. Swagger Editor also has a built-in Postman-like interface for interacting with API endpoints, though it is not as good as Postman. You can serve your own local instance of Swagger Editor by following the instructions in the "Tools" section, below.

We maintain a style guide for the Currencycloud API documentation. See STYLE_GUIDE.md.

API Versions

The current version of the API is the latest tagged release and matches the documentation for the current Currencycloud API. Changes merged in master, but not yet part of a release, are not available on the API. The latest tagged release should be used instead of the swagger definition in master directly.

Releases

Current

For details on the contents of releases see CHANGELOG

Previous

Deprecation Policy

Deprecated features will no longer be supported in the next release 3 months after the release that the deprecation notification was included. The release that the feature was deprecated in is denoted by the tag x-deprecation-version.

For more details see Developer Center Deprecation Policy

Tools

Local Swagger Editor

Docker provides a simple way to start a local Swagger Editor with the API schema

docker pull swaggerapi/swagger-editor
docker run -p 8866:8080 -v $(pwd)/src:/tmp -e SWAGGER_FILE=/tmp/reference.yaml swaggerapi/swagger-editor

which can be accessed then via http://localhost:8866 and after editing new version can be saved.

Alternatively follow the Swagger Editor's local build procedure.

Remote Swagger Editor

Online editor is available at https://editor.swagger.io/.

Postman

The reference.yaml file is a "single source of truth" for the Currencycloud API. It can be used to auto-generate documentation, tests, and even mock endpoints for development purposes. The file is also compatible with Postman, a popular app that makes it easy to manually test API endpoints.

For a step-by-step guideline on how to configure Postman, please see this guide

Once Postman is installed and configured it is not mandatory to configure a Postman environment, since the OpenAPI file contains all the information required to generate client interfaces for the Currencycloud API, but it is still useful to setup some environment variables to prepopulate API input parameters while testing. The following environment variables are recommended:

  • login_id: The email address that you use to login to your Currencycloud account.
  • api_key: Your unique Currencycloud API key that you retrieved from your Currencycloud account.
  • X-Auth-Token: Keep this empty initially. Update it when you have an authentication token from the Login endpoint.

Click on "Collections" on the left side of the Postman UI, and then click the icon to "Import collection". Under "Upload files", select the copy of reference.yaml on your computer. All of the Currencycloud endpoints defined in the OpenAPI document will be imported into a new Postman collection.