@credify/api-docs

Credify API doc OpenAPI Definition

API clients and models

This repository automatically generates API clients and models based on OpenAPI Spec using OpenAPITools/openapi-generator-cli.
Please install the latest version with npm or yarn.

Install

// Generated API clients use `axios` as HTTP client.
yarn add -D @credify/api-docs axios@0.21.1

yarn install

Usage

index contains all the definitions regarding API endpoints.
types directory contains all the definitions regarding API request/response data.

// By importing `@credify/api-docs/apiClients/v1`, you can use the API v1.
import { AuthApiFactory, CommonApiFactory, AccessTokenResponse, CommonResponse, Phone } from "@credify/api-docs/apiClients/v1";
// By importing `@credify/api-docs/apiClients/v2`, you can use the API v2.
import { OnboardingApiFactory } from "@credify/api-docs/apiClients/v2";
// By importing `@credify/api-docs/apiClients/integration`, you can use the API integration v1.
import { ClaimProviderApiFactory, EvaluatedOffersListResponse } from "@credify/api-docs/apiClients/integration";
// By importing `@credify/api-docs/apiClients/integration-v2`, you can use the API integration v2.
import { BNPLProviderApiFactory, GetCompletedBnplProviderList200Response } from "@credify/api-docs/apiClients/integration-v2";
// By importing `@credify/api-docs/apiClients/products`, you can use the API products.
import { BNPLApiFactory, BalanceCheckResponse } from "@credify/api-docs/apiClients/products";

/*
* Simple way to make a request is to create an API client with an API factory function.
* If you want to use the API with the Auth tag, you need to use the AuthApiFactory function.
* Named in this way - XXXApiFactory.
*  Organization -> OrganizationApiFactory
*  Offers       -> OffersApiFactory
* */
const apiClient = AuthApiFactory();
const response: AccessTokenResponse = await apiClient.generateAccessToken("X_API_KEY");


/*
* You can pass parameters, for example accessToken, with a Configuration object when initializing an API client.
*  1. Initialize a ConfigurationParameters with some basic properties.
*  2. Set additional information as a baseOptions property if needed, for example, accept-language.
*  3. Initialize a Configuration with the ConfigurationParameters.
*  4. Create an API client with a API factory function.
* 
* 
* The basePath can be changed for each environment.
* This needs to be handled by the user of the API client;
* You don't need to care about the API version in the path, like `/v1/~` or `/v2/~`.
* 
* in the case of the passport app, the getBaseUrl function can be used.
*   export const APP_API_BASE_URL = getBaseUrl();
*   export const getBaseUrl = (): string => {
*     let env = getEnvironment();
*     switch (env) {
*         case Environment.Dev:
*             return "https://dev-api.credify.ninja";
*         case Environment.SIT:
*             return "https://sit-api.credify.ninja";
*         case Environment.UAT:
*             return "https://uat-api.credify.dev";
*         case Environment.Sandbox:
*             return "https://sandbox-api.credify.dev";
*         case Environment.Prod:
*             return "https://api.credify.one";
*         default:
*             return "https://dev-api.credify.ninja";
*     }
*   };
* */ 

const configParameters: ConfigurationParameters = {
    "apiKey" : "X_API_KEY",
    "accessToken" : "ACCESS_TOKEN",
    "basePath" : "https://dev-api.credify.ninja",
};
// Set additional information in an HTTP request header.
const baseOptions = {};
const headers = {
    "Accept-Language": "accept language setting",
    "X-Custom-Header": "custom header value"
};
baseOptions["headers"] = headers;
configParameters["baseOptions"] = baseOptions;

const configuration = new Configuration(configParameters);
const commonApi = CommonApiFactory(configuration);
const response: PrivateKeyResponse = await commonApi.getKeyPairs();


// You can pass a payload when calling a function.
const phoneApi = PhoneNumberApiFactory(configuration);
const updatePhonePayload: Phone = {
    phone_number: "000000000000",
    country_code: "+84"
};
const response: CommonResponse = await phoneApi.updatePhoneNumber(updatePhonePayload);

Deployment

Once you finish your changes on this repository, please merge a pull request named Release for vX.X.X. GitHub Action will be kicked off to tag them, create releases, and deploy the latest package to @credify/api-docs - npm.

GitHub Actions

tagpr

• This automatically creates and updates a pull request for unreleased items, tags them when they are merged, and create releases.
• This increases the patch version by default. To increase the minor/major version, please add the label tagpr:major ortagpr:minor to the pull request.

npm

• This builds and publish new package to the npm repository.

---

Working on your OpenAPI Definition

Install

1. Install Node JS.
2. Clone this repo and run yarn in the repo root.

Usage

yarn start

Generate documentation previews for API definitions on your local machine.

yarn build

Combine separate API definition file into one. The generated file is located under the dist folder.

yarn ts-build:v1 yarn ts-build:v2 yarn ts-build:integration-v1 yarn ts-build:integration-v2 yarn ts-build:products

Build and generate API clients for each API definition file.

yarn ts-build

Build and generate API clients for all API definition files.

If you want to run ts-build command on your local machine, please make sure Java 8 or above is installed (Tips: run java -version to check the version), and export JAVA_HOME in order to use the supported Java version:

export JAVA_HOME=`/usr/libexec/java_home -v 1.8`
export PATH=${JAVA_HOME}/bin:$PATH

Contribution Guide

Below is a sample contribution guide. The tools in the repository don't restrict you to any specific structure. Adjust the contribution guide to match your own structure. However, if you don't have a structure in mind, this is a good place to start.

Update this contribution guide if you adjust the file/folder organization.

The .redocly.yaml controls settings for various tools including the lint tool and the reference docs engine. Open it to find examples and read the docs for more information.

Schemas

Adding Schemas

1. Navigate to the docs/components/schemas folder.
2. Add a file named as you wish to name the schema.
3. Define the schema.
4. Refer to the schema using the $ref (see example below).

Example Schema

This is a very simple schema example:

type: string
description: The resource ID. Defaults to UUID v4
maxLength: 50
example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

This is a more complex schema example:

type: object
properties:
  id:
    description: The customer identifier string
    readOnly: true
    allOf:
      - $ref: './ResourceId.yaml'
  websiteId:
    description: The website's ID
    allOf:
      - $ref: './ResourceId.yaml'
  paymentToken:
    type: string
    writeOnly: true
    description: |
      A write-only payment token; if supplied, it will be converted into a
      payment instrument and be set as the `defaultPaymentInstrument`. The
      value of this property will override the `defaultPaymentInstrument`
      in the case that both are supplied. The token may only be used once
      before it is expired.
  defaultPaymentInstrument:
    $ref: './PaymentInstrument.yaml'
  createdTime:
    description: The customer created time
    allOf:
      - $ref: './ServerTimestamp.yaml'
  updatedTime:
    description: The customer updated time
    allOf:
      - $ref: './ServerTimestamp.yaml'
  tags:
    description: A list of customer's tags
    readOnly: true
    type: array
    items:
      $ref: './Tags/Tag.yaml'
  revision:
    description: >
      The number of times the customer data has been modified.

      The revision is useful when analyzing webhook data to determine if the
      change takes precedence over the current representation.
    type: integer
    readOnly: true
  _links:
    type: array
    description: The links related to resource
    readOnly: true
    minItems: 3
    items:
      anyOf:
        - $ref: './Links/SelfLink.yaml'
        - $ref: './Links/NotesLink.yaml'
        - $ref: './Links/DefaultPaymentInstrumentLink.yaml'
        - $ref: './Links/LeadSourceLink.yaml'
        - $ref: './Links/WebsiteLink.yaml'
  _embedded:
    type: array
    description: >-
      Any embedded objects available that are requested by the `expand`
      querystring parameter.
    readOnly: true
    minItems: 1
    items:
      anyOf:
        - $ref: './Embeds/LeadSourceEmbed.yaml'

Using the $ref

Notice in the complex example above the schema definition itself has $ref links to other schemas defined.

Here is a small excerpt with an example:

defaultPaymentInstrument:
  $ref: './PaymentInstrument.yaml'

The value of the $ref is the path to the other schema definition.

You may use $refs to compose schema from other existing schema to avoid duplication.

You will use $refs to reference schema from your path definitions.

Editing Schemas

1. Navigate to the docs/components/schemas folder.
2. Open the file you wish to edit.
3. Edit.

Paths

Adding a Path

1. Navigate to the docs/paths folder.
2. Add a new YAML file named like your URL endpoint except replacing / with @ and putting path parameters into curly braces like {example}.
3. Add the path and a ref to it inside of your openapi.yaml file inside of the docs folder.

Example addition to the openapi.yaml file:

'/customers/{id}':
  $ref: './paths/customers@id@[e-mail]'

Here is an example of a YAML file named customers@{id}.yaml in the paths folder:

get:
  tags:
    - Customers
  summary: Retrieve a list of customers
  operationId: GetCustomerCollection
  description: |
    You can have a markdown description here.
  parameters:
    - $ref: '../components/parameters/collectionLimit.yaml'
    - $ref: '../components/parameters/collectionOffset.yaml'
    - $ref: '../components/parameters/collectionFilter.yaml'
    - $ref: '../components/parameters/collectionQuery.yaml'
    - $ref: '../components/parameters/collectionExpand.yaml'
    - $ref: '../components/parameters/collectionFields.yaml'
  responses:
    '200':
      description: A list of Customers was retrieved successfully
      headers:
        Rate-Limit-Limit:
          $ref: '../components/headers/Rate-Limit-Limit.yaml'
        Rate-Limit-Remaining:
          $ref: '../components/headers/Rate-Limit-Remaining.yaml'
        Rate-Limit-Reset:
          $ref: '../components/headers/Rate-Limit-Reset.yaml'
        Pagination-Total:
          $ref: '../components/headers/Pagination-Total.yaml'
        Pagination-Limit:
          $ref: '../components/headers/Pagination-Limit.yaml'
        Pagination-Offset:
          $ref: '../components/headers/Pagination-Offset.yaml'
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '../components/schemas/Customer.yaml'
        text/csv:
          schema:
            type: array
            items:
              $ref: '../components/schemas/Customer.yaml'
    '401':
      $ref: '../components/responses/AccessForbidden.yaml'
  x-code-samples:
    - lang: PHP
      source:
        $ref: '../code_samples/PHP/customers/get.php'
post:
  tags:
    - Customers
  summary: Create a customer (without an ID)
  operationId: PostCustomer
  description: Another markdown description here.
  requestBody:
    $ref: '../components/requestBodies/Customer.yaml'
  responses:
    '201':
      $ref: '../components/responses/Customer.yaml'
    '401':
      $ref: '../components/responses/AccessForbidden.yaml'
    '409':
      $ref: '../components/responses/Conflict.yaml'
    '422':
      $ref: '../components/responses/InvalidDataError.yaml'
  x-code-samples:
    - lang: PHP
      source:
        $ref: '../code_samples/PHP/customers/post.php'

You'll see extensive usage of $refs in this example to different types of components including schemas.

You'll also notice $refs to code samples.

Code samples

1. Navigate to the docs/code_samples folder.
2. Navigate to the <language> (e.g. PHP) sub-folder.
3. Navigate to the path folder, and add ref to the code sample.

You can add languages by adding new folders at the appropriate path level.

More details inside the code_samples folder README.