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
        }]
    }
}

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