API Tools

past, present and future

PAST

  • Undocumented APIs

  • Lack of design consistancy

  • No design review

Undocumented APIs

Ajax End Points

  • missing documentation
  • lack of change management
  • some wiki pages
  • mostly outdated
  • not maintained

Design Consistency

Ajax End Points

  • no api design standards
  • not restful

Design review

Ajax End Points

  • no design reviews
  • limited team collaboration

Current

  • RAML Design & Definition
  • KRAML Tools
  • API Design
  • Limitations
  • Design
  • Document
  • Share
  • Build
  • Test

RESTful API Modeling Language

RAML

Single source of truth

  • Human readable
  • Machine readable
  • Based on YAML
  • API Workbench

Surefire RAML

#%RAML 1.0
title: Personal Loan Surefire JSON Endpoints
version: draft
baseUri: https://surefire.creditkarma.com/

#Libraries
uses:
  Payload: !include types/payloadTypes.raml
  DataTypes: !include types/dataTypes.raml
  NumericId: !include types/numericId.raml
  CK: !include lib/ck-php-core-spec/commonTypes.raml

resourceTypes:
  offers: !include types/offersResourceType.raml

# TODO: compress these down into fewer resources where common structure is ensured
/personal-loans/{version}:

  /users/{numericId}:
    uriParameters:
      numericId: CK.numericId

    /offers:
      type: offers
      description: |
        A user can have multiple offers that all are type PersonalLoans.
        If you ask for a user's offers, you will get a user's offers. If you want ITA or some other, apply the filters.

API Workbench Demo

KRAML

Credit Karma Opinionated RAML

  • Dates
  • Integers
  • Return objects not arrays
  • Formatted Text

Kraml Tools

  • Kraml Parser
  • Kraml Linter
  • Kraml Codegen
  • Contract Test Tool

Credit Karma Raml Tools

Confluence: Search RAML Tools

Linting

> npm install --save-dev @ck/kraml-lint
> echo '{"extends": "@ck/kraml-lint/config/CKConfig.js"}' >> .kraml-lintrc
> node_modules/.bin/kraml-lint path/to/your.raml

{
    "scripts": {
        "test": "kraml-lint path/to/your.raml"
    }
}

add test to package.json

The Kraml Linter checks that RAML projects for consistency and standards.

Codegen

Uses RAML as a source of truth for generating Server and Client code

PHP

Server side contract generation to insure servers generate valid results

ObjectiveC / Java

Client side generation to make consuming APIs easier

Contract Test Tool

According to your RAML file, I can hit X endpoint with Y parameters and expect Z response structure – right?  

 

The contract test tool takes your RAML to task and actually tests this.

API Design

{
    "account": {
        "status": 1,
        "type": 2,
        "remarks": "",
        "times": [{
            "days": 30,
            "late": 0
        }, {
            "days": 60,
            "late": 0
        }]
    }
}
Account status Open
Type Flexible Spending Credit Card
Responsibility Individual
Remarks
Times 30/60/90 days late 0/0/0

API Design Improved

{
    "details": [
        ["Account status", "Open"],
        ["Type", "Flexible Spending Credit Card"],
        ["Responsibility", "Individual"],
        ["Remarks",""],
        ["Times 30/60/90 days","0/0/0"]
    ]
}

Limitations

  • Large API surface as services grow
  • Pushing client concerns into service
  • Multiple trips
  • Versioning

Future

  • Common Authentication & API
  • GraphQL

Common Authentication & API

Standardizing on API.CREDITKARMA.COM

  • Update mobile API to support auth tokens
  • Refactor native apps to use tokens
  • Create all new end points in API

GraphQL

  • Product / front end centric
  • Client-specified queries
  • Backwards Compatible
  • Strongly-typed
  • Introspective

Graphql Demo

CK API Tools

By Nick Nance

CK API Tools

an introduction

  • 1,208