The document provides a comprehensive overview of RESTful APIs, outlining key principles such as client-server architecture, statelessness, and resource manipulation through HTTP verbs. It discusses the importance of versioning, error handling with HTTP status codes, and the use of JSON Web Tokens (JWT) for authorization and information exchange. Additionally, it touches on various data query languages including GraphQL and provides guidelines for effective API documentation.

1. API
Masters Academy, 2018

2. Application programing interface

3. REST (Representational State Transfer)
REST is a software architectural style that
defines a set of constraints to be used for
creating web services.
● Client–server architecture
● Statelessness
● Cacheability
● Layered system
● Uniform interface
○ Resource identification in requests
○ Resource manipulation through
representations
○ Self-descriptive messages

4. Naming convention
1. Keep your URL simple and intuitive.
2. Keep Verbs out of your base URLs.
3. Use HTTP verbs like GET, POST, (UPDATE, DELETE) to work on the
collections.
4. Plural names are better than singular names.
5. Some companies use singular but we use the plural.
6. Use concrete names then using short names.

5. GOOD
BAD

6. Error Handling and status codes
Use HTTP status codes. For example:
● 200 Ok (All went well)
● 400 bad requests (Some required PARAM is missing)
● 401 – Unauthorized (User, not login in. Consumer (Web app, mobile app)
of this API should redirect to Login page.)
● 403 Forbidden/ Access denied (logged user does not have access to this
resource)
● 500 Internal server error (something went wrong on server)

7. Versioning
Versioning is one of the most important considerations when designing your Web
API.
Never release an API without using version numbers.
Use /version/resource. Examples:
● /v1/projects
● /v1/projects/:id
● /v2/user/:id/projects

8. Pagination and Partial request
1. /v1/projects?limit=25&offset=50
Limit: number of projects
Offset: Skip these records
2. Use partial response syntax.
/v1/projects/?fields=name,id,stage

9. JSON Web Tokens
JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting
information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. JWTs can be
signed using a secret (with the HMAC algorithm) or a public/private key pair using RSA or ECDSA.
When should you use JSON Web Tokens?
Here are some scenarios where JSON Web Tokens are useful:
● Authorization: This is the most common scenario for using JWT. Once the user is logged in, each subsequent request will
include the JWT, allowing the user to access routes, services, and resources that are permitted with that token. Single Sign On
is a feature that widely uses JWT nowadays, because of its small overhead and its ability to be easily used across different
domains.
● Information Exchange: JSON Web Tokens are a good way of securely transmitting information between parties. Because
JWTs can be signed—for example, using public/private key pairs—you can be sure the senders are who they say they are.
Additionally, as the signature is calculated using the header and the payload, you can also verify that the content hasn't been
tampered with.

10. JWT structure (xxxxx.yyyyy.zzzzz)
● Header (xxxxx)
{
"alg": "HS256",
"typ": "JWT"
}
this JSON is Base64Url encoded to form the first part
of the JWT.
● Payload (yyyyy)
JSON object that cat contains any info.
{
"sub": "1234567890",
"name": "John Doe",
"admin": true
}
this JSON is Base64Url encoded to form the first part
of the JWT.
● Signature (zzzzz)
based on Header and Payload with using
selected algoritm
HMACSHA256(
base64UrlEncode(header) + "."
+ base64UrlEncode(payload),
secret)

11. Query languages or data query languages (DQLs) are computer languages
used to make queries in databases and information systems.
● Cypher is a query language for the Neo4j graph database;
● GraphQL is a data query language developed by Facebook as an alternate to REST and ad-hoc
webservice architectures.
● LINQ query-expressions is a way to query various data sources from .NET languages
● LDAP is an application protocol for querying and modifying directory services running over TCP/IP;
● ReQL is a query language used in RethinkDB;
● SQL is a well known query language and data manipulation language for relational databases;
● XQuery is a query language for XML data sources;
● XPath is a declarative language for navigating XML documents;

12. GraphQL
is an open-source data query and manipulation language for APIs, and a runtime for fulfilling queries with existing data.[2] GraphQL
was developed internally by Facebook in 2012 before being publicly released in 2015.[3] On 7 November 2018, the GraphQL project
was moved from Facebook to the newly-established GraphQL foundation, hosted by the non-profit Linux Foundation.
Describe your data
type Project {
name: String
tagline: String
contributors: [User]
}
Ask for what you want
{
project(name:
"GraphQL") {
tagline
}
}
Get predictable results
{
"project": {
"tagline": "A query
language for APIs"
}
}

14. GraphQL ecosystem
Servers
● https://www.apollographql.com/
● GraphQL-JS
● GraphQL-Server
● Other
Clients
● Relay
● Apollo
SaaS
● Graphcool
● Scaphold
Resources
● GraphQL.org
● LearnGraphQL
● LearnApollo
● Apollo Blog
● GraphQL Weekly
● Hashbang Weekly
● Freecom
● Awesome GraphQL

15. REST vs GraphQL

16. REST
● Server driven selection
● Fetching multiple resources
● More in depth analytics
GraphQL
● Caching
● Architecture
● Exposed for arbitrary requests
● Rigidness of queries
● Non existent monitoring
Problems

17. API Documentation
Title
<Additional information about your API call. Try to use verbs
that match both request type (fetching vs modifying) and
plurality (one vs multiple).>
● URL
<The URL Structure (path only, no root url)>
● Method:
<The request type>
GET | POST | DELETE | PUT
● URL Params
<If URL params exist, specify them in accordance with
name mentioned in URL section. Separate into
optional and required. Document data constraints.>
● Required:
id=[integer]
● Optional:
photo_id=[alphanumeric]
● Data Params
<If making a post request, what should the body
payload look like? URL Params rules apply here too.>
● Success Response:
<What should the status code be on success and is
there any returned data? This is useful when people
need to to know what their callbacks should expect!>
Code: 200
Content: { id : 12 }
● Error Response:
<Most endpoints will have many ways they can fail.
From unauthorized access, to wrongful parameters
etc. All of those should be liste d here. It might seem
repetitive, but it helps prevent assumptions from being
made where they should be.>
Code: 401 UNAUTHORIZED
Content: { error : "Log in" }
● Sample Call:
<Just a sample call to your endpoint in a runnable
format ($.ajax call or a curl request) - this makes life
easier and more predictable.>
● Notes:
<This is where all uncertainties, commentary,
discussion etc. can go. I recommend timestamping
and identifying oneself when leaving comments
here.>

18. Show User
Returns json data about a single user.
● URL
/users/:id
● Method:
GET
● URL Params
● Required:
id=[integer]
● Data Params
None
● Success Response:
Code: 200
Content: { id : 12, name : "Michael Bloom" }
API Documentation example
● Error Response:
Code: 404 NOT FOUND
Content: { error : "User doesn't exist" }
OR
Code: 401 UNAUTHORIZED
Content: { error : "You are unauthorized to
make this request." }
● Sample Call:
$.ajax({
url: "/users/1",
dataType: "json",
type : "GET",
success : function(r) {
console.log(r);
}
});

19. RESTful API Description Languages
● OpenAPI Specification
○ URL: https://openapis.org/
○ developer: Open API Initiative (OAI), originally developed as "Swagger" specification by Wordnik, SmartBear Software
● RESTful API Modeling Language (RAML)
○ URL: http://raml.org/
○ developer: Mulesoft, http://www.mulesoft.com/
● API Blueprint
○ URL: https://apiblueprint.org/
○ developer Apiary, https://apiary.io/company
● API Builder
○ URL: https://www.apibuilder.io/
○ developers: HBC, Flow Commerce
Full list