apidays LIVE LONDON - Data Retrieval via APIs - Showdown of GraphQL vs ODATA by Sumit Amar

Sumit Amar
@ChiefCoder
October 28, 2020

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

• 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 the list of attributes from an instance (SELECT)]
query {
players {
name
}
}
{
"data":{
"players ” : [ {
"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"
}
]
}

• Expressions to filter list of records from a collection (WHERE)
query {
players(filter:{ name : {eq : “A B”}}) {
id,
name
}
}
query {
player(id:”1a”) {
id,
name
}
}
{
"data":{
"players ” : [ {
"id":"1a",
"name":"A B"
}
]
}
{
"data":{
"player” : {
"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"
}
]
}

• first - Number of records to retrieve (FETCH orTOP or LIMIT)
• offset - Skip to this record number (OFFSET)
query {
players(first:1 offset:2)
{
id,
name,
country_code,
game_id
}
}
{
"data": {
"players": [
{
"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 body of an aggregation/reference entity (similar to adding a JOIN)
query {
player(id:”1a”)
{
id,
name,
country_code,
game {
id,
name
}
}
}
{
"data": {
"player":
{
"id":"1a",
"name":"A B",
"game":{
"id":"1g",
"name":"Contra"
}
}
}
}

• $orderby – sort an entity result using one or more fields
• GET /players?$orderby=name
{
"links":[
{
"href":"<baseURL>/players?$orderby=name ",
},
{
"rel":"games"
}
],
"data":[
{
"id":"1a",
"name":"A B",
"game_id":"1g"
}
}
]
}

• Sort using order by clause
query {
players(orderby: {name : asc})
{
id,
name,
country_code,
game_id
}
}
{
"data": {
"players": [
{
"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
• Quick comparison of ODATA and
GraphQL

apidays LIVE LONDON - Data Retrieval via APIs - Showdown of GraphQL vs ODATA by Sumit Amar

More Related Content

What's hot (20)

Similar to apidays LIVE LONDON - Data Retrieval via APIs - Showdown of GraphQL vs ODATA by Sumit Amar (20)

More from apidays (20)

Recently uploaded (20)

apidays LIVE LONDON - Data Retrieval via APIs - Showdown of GraphQL vs ODATA by Sumit Amar