Embracing Change without Breaking the World - DEV319 - re:Invent 2017

© 2017, Amazon Web Services, Inc. or its Affiliates. All rights reserved.
Embracing Change Without
Breaking The World
J i m F l a n a g a n – S o f t w a r e E n g i n e e r – A W S C r y p t o g r a p h y
K y l e T h o m s o n – S o f t w a r e E n g i n e e r – A W S S D K
D E V 3 1 9
N o v e m b e r 3 0 , 2 0 1 7
AWS re:INVENT

Introduction
• AWS has 90+ services and deploys API updates several times a week (often daily)
• Backwards compatibility is necessary

Who are we?
• API review bar-raisers
• Experienced API reviewers and library designers
• Responsible for quality of AWS APIs
• Ensure backwards compatibility of API changes

Agenda
• Definitions
• What’s backwards compatibility and why is it important?
• What’s an API (by way of example)?
• Changing an API
• What’s safe to do in the API?
• How should we design our clients?
• API constraints and validation
• Client-side concerns
• Exceptions
• Undocumented API contracts
• Sharing shapes
• Backwards compatibility rules

Definitions

How APIs evolve relative to clients
API
Client

API
Client
API
v2
Client
v2

API
Client
API
v2
Client
v2
API
v3
Client
v3
API
v4
Client
v4
API
vN
Client
vN

API
Client
API´
Client´

Client
API´
Client´

Anatomy of a Web API—resources
Trip

Trip
travelers: [string]
description: string
…
“Shape"
“Member”

Trip
travelers: [string]
description: string
flight: Flight
Flight
airline: string
status: string
…

Anatomy of a Web API
PutTrip
GetTrip
ListTrips

PUT /Trips
GET /Trips/{id}
GET /Trips

123
GetTrip
{ “travelers”: [“Jim”],
“description”: “re:Invent” }

123
GetTrip
{ “travelers”: [“Jim”],
“description”: “re:Invent” }
Input
shape

321
GetTrip
ResourceNotFound

Summary of definitions
• Resources—things that an API manages
• Shape—some structure with members
• Input shape—a top-level request shape passed to an operation
• Output shape—a top-level response shape return from an operation
• Error shape—a structure that represents an error response from an operation
• Member—belongs to a shape represents some property
• Operation—something the service exposes that can be invoked (e.g. getTrips)

Changing an API

Adding/removing
Trip
travelers: [string]
description: string
origin: string

Adding/removing
Trip
travelers: [string]
description: string

Adding members
public final class Trip {
private final List<String> travelers;
private final String description;
public Trip(List<String> travelers, String description) {
this.travelers = travelers;
this.description = description;
}
public List<String> getTravelers() {
return travelers;
}
public String getDescription() {
return description;
}
}

Adding members
List<String> travelers = Collections.singletonList("Jim");
Trip myTrip = new Trip(travelers, "re:Invent");

Adding members to the constructor
public Trip(List<String> travelers, String description, String origin) {
this.origin = origin;
}

Adding members to the constructor
}
Won’t
compile

Constructor overload
public Trip(List<String> travelers, String description) {
this(travelers, description, null);
}
}
Trip myTrip = new Trip(travelers, "re:Invent”, “USA”);

All constructor combinations
public Trip(List<String> travelers, String description, String origin)
public Trip(List<String> travelers, String description)
public Trip(List<String> travelers)
public Trip(String description, String origin)
public Trip(String description)
public Trip(List<String> travelers, String origin)

public Trip(String origin)

public Trip(String origin)
Clash!

Languages with default values

Adding members
private List<String> travelers;
private String description;
public Trip() { }
public void setTravelers(List<String> travelers) { this.travelers = travelers; }
public void setDescription(String description) { this.description = description; }
/** getters omitted **/
}

Adding members
public Trip() { }
/** getters omitted **/
}
Trip trip = new Trip();
trip.setTravelers(travelers);
trip.setDescription("re:Invent");

Adding members
private String origin;
public Trip() { }
public void setOrigin(String origin) { this.origin = origin; }
}

Adding members
private String origin;
public Trip() { }
public void setOrigin(String origin) { this.origin = origin; }
}
Models
are
mutable

Adding members
private Trip(Builder builder) {
this.travelers = builder.travelers;
this.description = builder.description;
}
public static Builder builder() { return new Builder(); }
public static class Builder {
public Builder travelers(List<String> travelers) { this.travelers = travelers; return this; }
public Builder description(String description) { this.description = description; return this; }
public Trip build() { return new Trip(this); }
}
}

Adding members
}
}
}
Members
are final

Adding members
}
}
}
Constructor
is private

Adding members
}
}
}
Trip trip = Trip.builder()
.travelers(travelers)
.description("re:Invent")
.build();

Adding members
private final String description, origin;
this.origin = builder.origin;
}
private String description, origin;
public Builder origin(String origin) { this.origin = origin; return this; }
}
}

Constraints & Validation

Adding—caveats
Trip
travelers: [string]
description: string
origin: string
destination: stringRequired

Adding—caveats
Flight
airline: string
status: FlightStatusEnum
…

Adding—caveats
Requested
RejectedBooked Terminal
state
Processing

Adding—caveats
Requested
Processing
RejectedBooked Error

Adding—caveats
Requested
Processing
…
Review

Enumerations in code
public final class Flight {
private final String airline;
private final FlightStatus status;
private Flight(String airline, FlightStatus status) {
this.airline = airline;
this.status = status;
}
public String getAirline() { return airline; }
public FlightStatus getStatus() { return status; }
}
public enum FlightStatus {
REQUESTED, PROCESSING, BOOKED, REJECTED;
}

private final String status;
private Flight(String airline, String status) {
this.airline = airline;
this.status = status;
}
public String getAirline() { return airline; }
public String getStatus() { return status; }
}
FlightStatus.valueOf(flight.getStatus());

REQUESTED, PROCESSING, BOOKED, REJECTED, SDK_UNKNOWN;
}
public FlightStatus getStatus() {
try {
return FlightStatus.valueOf(status);
} catch (IllegalArgumentException e) {
return FlightStatus.SDK_UNKNOWN;
}
}
}

REQUESTED, PROCESSING, BOOKED, REJECTED, SDK_UNKNOWN;
}
public FlightStatus getStatus() {
try {
return FlightStatus.valueOf(status);
} catch (IllegalArgumentException e) {
return FlightStatus.SDK_UNKNOWN;
}
}
public String getStatusAsString() { return status; }
}
switch(flight.getStatus()) {
case BOOKED: System.out.println("Yay!");
case SDK_UNKNOWN:
System.out.println("Unknown value: " +
flight.getStatusAsString());
}

Client side validation
this.travelers = Validate.hasSize(builder.travelers, 1);
this.description = Validate.notNull(builder.description);
}
@NotNull
public List<String> travelers() { return travelers; }
@NotNull
public String description() { return description; }
}
fun descriptionLength(): Int = trip.description().length

Client side validation
this.travelers = Validate.hasSize(builder.travelers, 1);
}
@NotNull
public List<String> travelers() { return travelers; }
@NotNull
public String description() { return description; }
}
fun descriptionLength(): Int = trip.description()?.length

Source Compatibility
public interface TripClient {
void putTrip(PutTripRequest request);
GetTripResponse getTrip(GetTripRequest request);
GetTripsResponse getTrips();
}
TripClient tripClient = ...;
tripClient.putTrip(putTripRequest);
response = tripClient.getTrip(getTripRequest);

Source Compatibility
PutTripResponse putTrip(PutTripRequest request);
GetTripResponse getTrip(GetTripRequest request);
GetTripsResponse getTrips();
}

Binary Compatibility
void putTrip(PutTripRequest trip);
}
PutTripResponse putTrip(PutTripRequest trip);
}
NoSuchMethod
Exception

Exceptions

Exceptions
PutFlight:
Input:
PutFlightRequest
Output:
Flight | ValidationError
| UnknownAirportError

Exceptions
PutFlightRequest
airline: string
date: dateTime
ValidationError
InvalidDateError

Exceptions
ValidationError
message: string
field: string
validationType: VTypeEnum

Undocumented API Contracts

Undocumented API contracts
Hyrum’s Law–With sufficient number
of users of an API, it does not matter
what you promise in the contract, all
observable behaviors of your system
will be depended on by somebody

”ListTripsRequest” : {
”nextToken”
…
}
”ListTripsResult” : {
”nextToken”
…
}

”ListTripsRequest” : {}
”nextToken” : “page2”
}
“items” : [ … ],
”nextToken” : ”page2” }

}

”ListTripsRequest” : {}
}
“items” : [ … ],
”nextToken” : ”10-20” }

”ListTripsResponse” : {
“items”: [ … ],
”nextToken” : “cGFnZTIK”
}

Sharing Shapes

Sharing shapes
UpdateFlight:
Input: Flight
Output: Flight

Sharing shapes
Flight
airline: string
status: FlightStatusEnum
lastModified: Date

Sharing shapes
UpdateFlight:
Input: UpdateFlightRequest
Output: Flight

Backwards Compatibility Rules

The Good (Dos)
API
• Adding members/shapes
• Adding intermediate (non-terminal) workflow
states
• Adding details to exceptions (error codes)
• Adding new opt-in exceptions
• Loosening constraints (e.g. increase max length)
Client
• Forward compatible (support all of the above)
• Focus on discoverability
The Bad (Don’ts)
API
• Removing/renaming members/shapes
• Changing the type of members
• Adding new terminal workflow states
• Adding exceptions without opt-in
• Tightening constraints (e.g. decrease max-length)
Client
• Validating API constraints
The Rules

Thank you!
D E V 3 1 9

Embracing Change without Breaking the World - DEV319 - re:Invent 2017

Recomendados

Recomendados

Más contenido relacionado

Similar a Embracing Change without Breaking the World - DEV319 - re:Invent 2017

Similar a Embracing Change without Breaking the World - DEV319 - re:Invent 2017 (20)

Más de Amazon Web Services

Más de Amazon Web Services (20)

Embracing Change without Breaking the World - DEV319 - re:Invent 2017