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:
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:
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:
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:
fbidwith value"apple"setwith value"pear"typewith 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
Keys are MUST be strings and MUST be wrapped in double quotes
"".Values in a JSON object can be another JSON object. For example, this is valid:
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.
Last updated