APIs

API is the acronym for Application Programming Interface, which is a software intermediary that allows two applications to talk to each other. Each time you use an app like Facebook, send a message, or check the weather on your phone, you’re using an API.

API is a general set of protocols and is deployed over the software to help it interact with some other software.

Public API usually require an API key. An API key is a simple encrypted string that identifies an application without any principal. They are useful for accessing public data anonymously, and are used to associate API requests with your project for quota and billing.

There are many types of API:

  • REST
  • SOAP
  • GraphQL and more…

To keep this short and more to the point, most jobs require RESTful API.

RESTful API is only geared towards web applications and mostly deals with HTTP requests and responses.

Basically, users send requests and the API then replies with a response.

Each API response consists of:

  • Status code (eg. 200)

    A status code falls into levels:

    • 2**

      Everything went well.

    • 4**

      Something went wrong.

    • 5**

      There was a server failure.

  • Response Headers

    They contain information about the server.

  • Response Body

    It contains the data, which is usually formatted in JSON.

HTTP

HTTP means HyperText Transfer Protocol.

As a request-response protocol, HTTP gives users a way to interact with web resources such as HTML files by transmitting hypertext messages between clients and servers.

HTTP is a method for encoding and transporting information between a client (such as a web browser) and a web server.

Common HTTP requests

  • CONNECT: The CONNECT method establishes a tunnel to the server identified by the target resource.
  • DELETE: The DELETE method deletes the specified resource.
  • GET: The GET method requests a representation of the specified resource. Requests using GET should only retrieve data.
  • HEAD: The HEAD method asks for a response identical to that of a GET request, but without the response body.
  • OPTIONS: The OPTIONS method is used to describe the communication options for the target resource.
  • PATCH: The PATCH method is used to apply partial modifications to a resource.
  • POST: The POST method is used to submit an entity to the specified resource, often causing a change in state or side effects on the server.
  • PUT: The PUT method replaces all current representations of the target resource with the request payload.
  • TRACE: The TRACE method performs a message loop-back test along the path to the target resource.

HTTP Status Codes

  • 2XX
    • 200: Everything is good. Successful request!
    • 201: New resource was created.
    • 204: Everything is good. Nothing to return!
  • 3XX
    • 304: Resource is same. Use cached version.
  • 4XX
    • 400: Bad request. Invalid URL/syntax.
    • 401: Invalid/wrong credentials.
    • 403: Athenticated user but does not have permission.
    • 404: Not found. Resource could not be accessed by the server.
  • 5xx
    • 500: Unexpected internal server error.

Pactical API

  • Create an API (C#)

    Use the dotnet CLI (at the time of writing, I am using dotnet 3.1 LTS) to create a ASP .NET Core Web API**

    This component was made by Stratis Dermanoutsos. The code can be found here.

    and, inside your browser, visit localhost/WeatherForecast. You should see text similar to

    This component was made by Stratis Dermanoutsos. The code can be found here.

    This is our data provided by the API.

    In the template’s code you can notice 2 files:

    • WeatherForecast.cs

      This is the class that describes the objects returned from our API.

    • WeatherForecastController.cs

      This is our controller that, in the template, generates several objects of type WeatherForecast with random values and is called when we visit the above link.

      Notice that every time we visit the link, we call the WeatherForecastController. In other words, we send a request and it generates a different response every time the link is visited.

      Pay attention to the [ApiController] and [HttpGet] attributes above the WeatherForecastController class and its Get() method respectively. They are important as:

      • [ApiController] indicates that a type and all derived types are used to serve HTTP API responses.
      • [HttpGet] identifies an action that supports the HTTP GET method.

      These make the API work as it does.

  • Access data through API (JavaScript)

    JavaScript (and, by extension, TypeScript) has a number of ways to access and work with API.

    The most popular ones are:

    • XMLHttpRequest
    • Fetch

    Differences:

    • Fetch makes it easier to make asynchronous requests.
    • Fetch handles responses better.
    • The Fetch API uses Promises, hence avoiding callback hell.

    Basically, Fetch is a better alternative to XMLHttpRequest.

    A simple example of getting data in JSON format

    This component was made by Stratis Dermanoutsos. The code can be found here.

Resources