Web services basics!

6 min readNov 13, 2019

Fellow learners, welcome!

I have been around for a while in the software industry, but in the realm of web programming, it’s still baby steps!

I want to use this blog to record and share my understanding of some of the fundamental concepts around web programming.

Networking basics

A webservice by definition cannot exist in isolation, it needs to connect with clients, databases, and other services in order to perform its job. Some of the fundamental terms forming the jargon of communication are:

Protocol —
Socket —
Port —
endpoint —
SSL —
Encrpytion and Encoding —
Signing —

Cookies

HTTP is a stateless protocol. If a user visits a site 100 times, Http will send the same web request 100 times, without letting the website know in any way that this particular user has been there before.

Now a site maybe interested to record usage/visit pattern by a user for purpose of analytics, or in case of websites that require a login, cookies help a user’s avoid sending his/her credentials with every API call, by passing on this information. Without a cookie doing this mundane job for the user, a user will have to pass his credentials on each call, spoiling his experience.

Needless to say, cookies help both the user and the website owners make more sense of the interaction.

Ownership of a cookie- Owner of a cookie is the domain that set the cookie on client’s visit to the website. For eg. google.com, amazon.com, or sub-domains like mail.yahoo.com.
Scope- a cookie is owned by a domain/subdomain, so the contextual information stored in a cookie can be passed only to owner domain, when a request is made to it.
Types of cookies — First-party vs Third-party cookies

If a cookie is set by a site on user visit in the user’s browser, the site can set a cookie for its domain or another domain.

If cookie is set for its domain, ie. owner domain is same as domain visited, it is a first-party cookie.

But, sometimes sites attempt to pass data about visit by user/user’s usage patterns to a ‘third’ site, by setting a cookie with owning domain as that third-party domain. Such cookies are called Third-party cookies.

Third-party cookies are frownable for obvious reasons, they try pass user’s behavior info to another domain for purposes such as target advertising etc.

So, presently many browsers tend to disallow third-party cookies from being stored in browser, and adblocker plugins tend to delete them.

Ref: https://www.opentracker.net/article/third-party-cookies-vs-first-party-cookies

Authentication(authN)

Two most well-known methods of authN are session-based and token-based authN.

Session based authentication —

When user logins, a session is created for user on server-side, and session id is shared with client. (authN info stored at server-side).
Client stores this session id in a cookie.
Session id is passed with each call to server, which helps validate that if this session id was issued by server, and if it is not expired yet.

Challenges —

scale — server needs to store session information. Memory usage on server, network call involved at API gateway to SessionService to validate session present. These add to memory-usage and latency.

Token based authentication —

When talking about tokens, we primarily refer to (Json-Web token)JWT tokens.

When user logins, an authentication service creates a JWT token and adds user info to this token. It can add other metadata such as user permissions to this token. It signs this token and returns it to client.
Service doesn’t store any session information about a loggedin user, that information is carried by JWT token at client-side.(authN info stored at client-side).
Service is saved from memory overhead in case of session-based authN.
With each client call, Jwt token is passed, server validates that it had signed it, if token validated, service decodes all user metadata provided in token. This metadata are called ‘Claims’, meaning these are claims made by Jwt token as being true info.
Authorization(authZ) — session-based authN needs to lookup user, and fetch his permissions to see if he is authorized to execute API, but with Jwt token, user permissions can be encoded in Jwt token at time of issuing token itself, thus authZ will be faster in this case.

Http response codes

401 (Unauthorized) — It implies an authentication error, ie. the web server doesn’t believe that the caller is who he claims to be. It is in general a temporary error in that the server assumes that there could be failure in authentication flow, or bad authentication info sent, or for example token expiry, so server encourages caller to call again. If a webserver is first point of contact, it can authenticate, and if failure happens it will return 401. If an application server is sitting behind web-server in flow, it will not even come to know of this call.
403 (Forbidden) — This response code implies the system has authenticated the caller, and believes that the caller is who he claims to be, BUT the system found that the caller doesn’t have the permission to call this API. This authorization check will actually happen in flow of calling that particular API, thus this response code is closely bound to application logic or the particular API, while a 401 can be simply thrown without even thinking which particular API is being hit.
200 (OK)— Request is successfully processed, and a response is returned.
204 (No content) — It is similar to 200 in that request is successfully processed but no response is returned.
502(Bad gateway) — It indicates that although connection was established, the client wasn’t able to get a response from server. Thus it falls in the category of server errors(5xx). It indicates a temporary-kind of error, which could be due to a network partition temporarily. Suggestion to client if it receives this response code is to retry with some delay.

Http connection configuration and management

The most common http connection model is client-server model. HTTP protocol basically works over TCP.

TCP connection involves setting up sockets on client and server. A connection in general is a 5-tuple (Protocol, clienthost, clientport, serverhost, serverport).

Thus a server can have multiple connections from same client, through different ports.

Now a connection is a costly resource, for both clients and servers, since it needs to simultaneously maintain many connections, often in order of 10000s. A connection requires memory to store metadata about a connection and will require other resources such as CPU time, disk I/O or network I/O to full incoming requests.

So, both client and server have a bias towards removing stale/unused connections, and favor reusing a connection to server more than one request instead of each request initiating a new connection.

Clients and servers tend to create a pool of connection objects which are reused to create new connections and make/serve requests.

Timeouts

Lifecycle of a connection can be governed by configuring various timeouts.

Following are some of important ones:

Connection timeout: This timeout happens at client-side. Within this duration a connection must get established between client and server. Post this duration client will stop trying. For example, if a web browser is trying to hit a website, it will stop trying to establish a connection post this timeout.
Socket timeout: This timeout happens at client-side. If this amount of time elapses without receiving new packet since client received the last packet, client returns a socket timeout.
Request timeout: This timeout occurs at server-side. If this amount of time elapses since server has received a ping from client, server assumes client is no longer available and closes the connection. Thus, client needs to periodically ping the server to ensure connection doesn’t timeout even if it is not sending an actual request.
Operation timeout or Call timeout: This timeout happens at client-side. When client initiates a call on server, call will timeout if a response is not received within this duration. In general, http clients can be configured to set a different read timeout or write timeout.
Idle timeout: This timeout happens in connection pool. If a connection remains idle for this duration, without processing a request it can be closed. ie. connection object can be destroyed. A related config is maxIdleConnections, which is self-explanatory.

Service-Oriented Architecture(SOA)

SOA involves different services talking to each other, requesting data, asking for validation or requesting to perform a job.

Service to Service communication in general involves establising a connection, sending a request, based on sync/async call, wait for response or not wait.

If a service A needs to call service B, service A will need to do few things:

request authorization by service B if API call requires authorization
request approval for QPS by serviceA, serviceB can choose to rate-limit serviceA. Even if service B doesn’t rate-limit serviceA, serviceB should know in advance the QPS which serviceA makes. This information about different client services will help serviceB to debug if it becomes latent, and can also throttle clients overshooting their limit.
get reasonable values for connection timeout, call timeout from serviceB owners.