Communication Protocols and APIs

Communication Protocols and APIs

Communication Languages

There are some languages, that is, formally defined syntactic systems, that are not programming languages but communication languages - they are designed specifically to facilitate communication through standardization. In 2003 the most important of these are UML, XML, and SQL. You should have some familiarity with all of these so that you can communicate well and decide when to use them.

UML is a rich formal system for making drawings that describe designs. Its beauty lies in that it is both visual and formal, capable of conveying a great deal of information if both the author and the audience know UML. You need to know about it because designs are sometimes communicated in it. There are very helpful tools for making UML drawings that look very professional. In a lot of cases UML is too formal, and I find myself using a simpler boxes and arrows style for design drawings. But I'm fairly sure UML is at least as good for you as studying Latin.

XML is a standard for defining new standards. It is not a solution to data interchange problems, though you sometimes see it presented as if it was. Rather, it is a welcome automation of the most boring part of data interchange, namely, structuring the representation into a linear sequence and parsing back into a structure. It provides some nice type- and correctness-checking, though again only a fraction of what you are likely to need in practice.

SQL is a very powerful and rich data query and manipulation language that is not quite a programming language. It has many variations, typically quite product-dependent, which are less important than the standardized core. SQL is the lingua franca of relational databases. You may or may not work in any field that can benefit from an understanding of relational databases, but you should have a basic understanding of them and the syntax and meaning of SQL.

URL

URL stands for Uniform Resource Locator and just like what it sounds like, it is the address of whatever you are looking for.

The components of a URL can be broken down as follow:

scheme://host:port/path?query

Seems familiar? Let's take a look at your own facebook profile then click on your "Photos" tab.

Your url should look something like this:

https://www.facebook.com/username/photos

As you can see, https is the scheme, www.facebok.com is the domain and the path is /username/photos.

Why is [www.facebook.com](http://www.facebook.com) the domain and not the host? That is for me to know and you to find out at your own time. Will link a more advanced article here if it is ever written.

Path

In this component, the /username portion varies based on your own username. The server is able to take in the value provided in /username as a variable. Then it will use it to return the correct data.

Query

Now, click on a photo and look at the url again.

You should see something like this:

https://www.facebook.com/photo.php?fbid=apple&set=pear&type=orange

What are all those weird things at the back? That is what we refer to as the query. Think of them as declaring variables to pass to the server.

In the example above, the server will receive the following:

• fbid with value "apple"

• set with value "pear"

• type with value "orange"

You should be able to infer that the beginning of the query is indicated by the question mark ?, and that the variables are separated by the ampersand sign &.

The order of the query parameters also do not matter, thus you can rearrange them however you want.

🤔 What if you want to pass in an array? There is actually no standard way to do this as it depends on the language and framework you use for your server.

Headers

Methods

The method is included with every HTTP request. It provides information to the server as to what to do with the resource. While there are many more, we will be focusing on 4 main methods for now. They are GET, POST, PUT and DELETE.

Their purposes are as follow:

GET

Retrieve data ONLY.

POST

Create new entry in data.

POST is generally more secure than GET

• Request data for POST is NOT stored in browser history nor cached, and is sent as part of the request body instead of the URI.

• GET cannot use complex object type as parameter, and only ASCII characters (as compared to binary)

PUT

Edit existing data. In some cases, we use PUT can create data if it does not exist.

DELETE

Delete data.

Body

Request body, or some call it the payload, is an optional part of a HTTP request which contain more data.

While there are many formats for request body, here at RH Devs we use JSON.

JSON

JSON stands for Javascript Object Notation. It is simply a format for representing data.

The object is wrapped in curly brackets and within, it contains key/value pairs. If you know python, it is very similar to a dictionary.

You can learn more about its syntax here: https://www.w3schools.com/js/js_json_syntax.asp

Key things to take note about JSON is

1. Keys are MUST be strings and MUST be wrapped in double quotes "".

2. Values in a JSON object can be another JSON object. For example, this is valid:

{
	"name": "bob",
	"family": {
		"dad": "greg",
		"mom": "susan"
	}
}

In the example above, it represents an object whose name is bob and contains a field called "family" which is another json object representing the names of his dad and mom.

Usage

We send data in the body usually when it is more complex. For example when we are creating a new user, it is more convenient and neater to pass everything in the JSON body instead of unwinding everything into the query string.

❗ GET does not support request body according to international standards. For GET requests, everything must be in the path or query.

Response

After you send a request, the server should return response. This will either contain data that you asked for, or confirmation on any action that you wanted to take.

Response Body

Similar to request body, the response body will contain a JSON object will all the necessary data.

What is JSON?

• JSON is an abbreviation that stands for JavaScript Object Notation. JSON is a lightweight text or data format that is easy for humans and computers to read. It is generally used for exchanging data between applications and web APIs or services. Although it has its origin in the JavaScript programming language, it is said to be language independent.

Status Codes

Apart from body, http responses also provide information using standardised status codes. Here are the ones that you must know and will be using often. Of course, there are a lot of other status codes for different scenarios out there.

❗ Status codes that start with 200s represent success, 400s represent client errors while 500s represent server errors.

200 OK

Request has succeeded.

400 Bad Request

The format of the request is bad, thus server is unable to understand it.

401 Unauthorized

User is not logged in, aka unauthenticated. Must log in to access resource.

403 Forbidden

User is logged in, but does not have permission to access resource.

404 Not Found

Server could not find the requested resource.

405 Method not Allowed

Requests uses a method that is not allowed for that resource.

500 Internal Server Error

Something went wrong with the server.

REST API

REST stands for REpresentational State Transfer, which means that the server will transfer a representation of the state of the resource that is being requested by the client.

A RESTful API is a web API (Application Programming Interface) or service that is based on an architectural style known as REpresentational State Transfer. REST defines how client applications can communicate with a RESTful API over HTTP. Client requests generally consists of a URI (Uniform Resource Identifier), an HTTP verb, a request header, and an optional request body. The most commonly used HTTP verbs include POST, GET, PUT, PATCH and DELETE, which corresponds to the CRUD (Create, Read, Update and Delete) Operations.

You should already know what API means.