Api design and usability

Sumit Amar
@ChiefCoder
October 22, 2019

• Be REST Assured (RESTfulness)
• HATEOAS
• ODATA for Data Retrieval
• Webhooks / Callbacks

• Resources / Entities Depiction
• HTTPVerb Usage
• Entity Relationships
• Status Codes
• Idempotency

• Pluralized nouns for entities
/users
• Actions using HTTP methods
GET /users
• Instances vs Collections
GET /users (returns a collection)
GET /users/1a (returns an instance)

• GET : Retrieve an instance or collection.
• POST : Creates an entity record.
• PUT : Updates a wholesome entity given its
ID.
• DELETE: Removes an entity given its ID
• PATCH: Partially updates an entity given its ID
• OPTIONS: Returns list of HTTP methods
available for an entity

• POST /players
{
"name":"A B",
"country_code":"US",
"phone":"000 000 0000"
}
Response 201 Created
{
"id":"1a",
"name":"A B",
"phone":"000 000 0000"
}

• POST /players/1a/trophies
{
"game":"Mario",
"trophy_name":"Champion"
}
Response: 201 Created
{
"id":"1t",
"game":"Mario",
}

• GET /players/1a
{
”id":”1a",
"name":"A B",
"phone":"000 000 0000",
"trophies":[
{
"id":"1t",
"game":"Mario",
},
{
"id":"2t",
"game":"Contra",
}
]
}

200 OK – ResponseOK. Should be used in GET (or PUT calls containing modified entity)
201 Created – Returned by a synchronous POST call creates an entity.
202 Accepted – Result of an long running operation by a POST call.
204 No Content – Result of a synchronous operation by a DELETE or PUT/PATCH
304 Not Modified – A cached response is returned
400 Bad Request – A malformed JSON request is sent
401 Unauthorized – API user is not authenticated. Bad credentials.
403 Forbidden – API user is not authorized. User roles don’t allow invoking an endpoint
409 Conflict – A race condition is found (validation of updated/modified timestamp
failed)
404 Not Found – Record for provided ID is not found, in case of GET, DELETE, PUT,
PATCH
408 RequestTimeout – Server couldn’t process the request in a specified time limit
414 URIToo Long – When the URL length limit of 2083 is hit
429Too Many Requests –Throttled API response, as a result of rate-limiting feature
500 Internal Server Error
501 Not Implemented – A requested method/operation is not implemented by service
503 Service Unavailable (with details if in debug mode) - In case of service based errors

• Repeated calls to the same resource must
recreate entities
• E.g. Repeatedly calling PUT /players/1a should
just update the record
• PATCH special case

• HypermediaAsThe Engine Of Application
State
• Sticky links in API responses
• Includes schema details
• Provides navigational elements (links) to
entities used in an API response

• {
"links":[
{
"href":"<baseURL>/players/1a",
"schema":"<baseURL>/schemas/$players",
"rel":"players | self"
},
{
"href":"<baseURL>/games/1g",
"schema":"<baseURL>/schemas/$games",
"rel":"games"
}
],
"data":{
"id":"1a",
"name":"A B",
"game_id":"1g"
}
}

• Open Data Framework (odata.org)
• Standard, predictable method to query
• SQL-like syntax in HTTP URLs
• Works atop RESTful GET endpoints
• Reduces cognitive dissonance in developers
• Server and client side libraries exist (Olingo for
Java,ASP.NET in .NET, and others)

• $select - Filter the list of attributes from an instance (SELECT)
• $filter - Expressions to filter list of records from a collection
(WHERE)
• $top - Number of records to retrieve (FETCH orTOP or LIMIT)
• $offset - Skip to this record number (OFFSET)
• $expand - Expand body of an aggregation/reference entity
(similar to adding a JOIN)
• $orderby - Sort the collections based on given column
name(s) (ORDER BY)
• $count - Return only the count of records in case of a
collections call. (COUNT)

• $select - Filter the list of attributes from an instance (SELECT)]
GET /players?$select=name
{
"links":[
{
"href":"<baseURL>/players?$select=name",
},
{
"rel":"games"
}
],
"data":[
{
"name":"A B"
}
]
}

• $filter - Expressions to filter list of records from a collection (WHERE)
GET /players?$filter=name eq ‘A B’&$select=id,name
{
"links":[
{
"href":"<baseURL>/players?$filter=name eq ‘A B’&$select=id,name ",
},
{
"rel":"games"
}
],
"data":[
{
"id":"1a",
"name":"A B"
}
]
}

• $top - Number of records to retrieve (FETCH orTOP or LIMIT)
• $offset - Skip to this record number (OFFSET)
• GET /players?$top=1&$offset=2 (Skips two records and takes 1)
{
"links":[
{
"href":"<baseURL> /players?$top=1&$offset=2",
},
{
"rel":"games"
}
],
"data":[
{
"id":"1a",
"name":"A B",
"game_id":"1g"
}
]
}

• $expand - Expand body of an aggregation/reference entity (similar to adding a JOIN)
• GET /players/1a?$expand=game
{
"links":[
{
"href":"<baseURL>/players/1a?$expand=game",
},
{
"rel":"games"
}
],
"data":
{
"id":"1a",
"name":"A B",
"game":{
"id":"1g",
"name":"Contra"
}
}
}

• $expand - Expand body of an aggregation/reference entity
• GET /players?$orderby=name
{
"links":[
{
"href":"<baseURL>/players?$orderby=name ",
},
{
"rel":"games"
}
],
"data":[
{
"id":"1a",
"name":"A B",
"game_id":"1g"
}
}
]
}

• Consider this in C#:
players.Any(p => p.address.city ==
"Foster City" &&
p.validateTrophies()).ToList<Player>();
• To Lambda expression in ODATA
/players?$filter=players/any(p:p/address/
city eq 'Foster City' and
p.validateTrophies())

{
"event" : "player.created",
"for": "<userId>",
"state": "active | inactive",
"description" : "webhook to receive details ",
"callback" : {
"url" : "https://clienturi/statusupdater",
"symkey" : ”a shared secret",
"access-token": "some access token for inbound auth",
"retries" : 5
}
}

• Use RESTful standards
• Use ODATA for predictable
retrieval
• Use appropriate status codes
• Make sure to account for
idempotency and concurrency

Api design and usability

More Related Content

What's hot (20)

Similar to Api design and usability (20)

Recently uploaded (20)

Api design and usability