How to design a good OutSystems API

How to Design a Good API? 2012-05-11

What is a Good API?

Easy to learn and memorize

Leads to readable code

Hard to misuse

Stable

Complete

Logging

Versioning

Scalablility

Security

Naming

Error Handling

User Stories

Granularity

What to consider?

• Who will use the API?

• How will they use it?

• Where will they use it?

• Put yourself in the developer’s shoes!

User Stories

Naming & Type

• Meaningful & Readable

• Consistent

• Strongly typed

GetOrderDetail()

GetEmployeeName()

CalculateTotalAmount()

3 x GetOrderLine()

Granularity

Error Handling

• Go public means you have to version

• No usage = deprecate old version

• It’s costly so avoid it!

Logging

Versioning

• Measure Usage

• Performance Monitoring

• Troubleshoot

• Service Center helps you out!

• Control access to API for internal

• HTTPS/SSL for Public APIs

• Token-based Authentication

Scalability

Security

• Use Partial Response

– Pagination

– Filtering

already scales!

API is a Product!

Scenarios

Master data

Most companies want to centralize their master data.

Error handling

Naming

Co

mp

osite

Ap

plic

atio

ns

Directory Performance

Management

- Nouns and Verbs

Versioning - TrueChange™

-Throw Exception

Security - Read-only Entities

Co

re B

usin

ess

Co

mp

on

en

ts

Employees

Information Provider

Airport management company provides real time flights’ information to their clients

Logging

Versioning

Scalablility

Security

Documentation

- Custom Audit

- New WebService

- Partial Response

- Lifetime Token

- API Document

Flight

Services

Flights Airports

3rd Parties

3-Tier Layer

Bank company wants a CRM application with a SOA approach. Security is critical.

User Stories

Security

Scalablility

- Int. Auth, Int. Net.

- Cache

- Resource based UI Layer

HomeBank CRM 1

Documentation - OutDoc

Busin

ess L

ayer

Account

Services

Accounts Customers

Customer

Services

2

Extranet

Insurance company wants to scale out claim management through partners.

Security

Large

Partners

Claim Management

Claim

Services

WebPortal

- HTTPS + S.Token

Granularity

Error Handling

- Use reUse

- Return error

Logging - Application Log

Small

Partners

What is a Good API?

Easy to learn and memorize

Leads to readable code

Hard to misuse

Stable

Complete

Steve Jobs

andre.vieira@outsystems.com nuno.baptista@outsystems.com