API Development and Documentation

Photo by Markus Spiske on Unsplash

API Development and Documentation

Van Nguyen (Zoe)'s photo
Van Nguyen (Zoe)
·

9 min read

Table of contents

This is a summary of what I learned in Full Stack Web Developer (Nanodegree) on Udacity. This article is about API development and Documentation.

I. Introduction to APIs

1. What are APIs?

If you look up the term API, you'll probably find a number of definitions—some of which are rather difficult to understand. But the key underlying idea is in the name Application Programming Interface. An API is an interface. It's something that has been created to help two different systems interact with one another.

A key idea to remember is that API functionality is defined independently of the actual implementation of the provider. Essentially, you don't need to understand the entirety of the application implementation in order to interact with it through the API. This has multiple benefits:

  • It doesn't expose the implementation to those who shouldn't have access to it
  • The API provides a standard way of accessing the application
  • It makes it much easier to understand how to access the application's data

Some frequently used APIs include:

  • Google Maps API allows users to access a large amount of data related to maps, routes, and places around the world. - Stripe API allows users to accept payments, send payouts, and manage businesses online.
  • Facebook API allows developers to integrate directly with the Facebook platform.
  • Instagram Basic Display API allows users of your app to get basic profile information, photos, and videos on their Instagram accounts.
  • Spotify API allows users to access a large amount of data related to music artists, albums, and tracks, directly from the Spotify Data Catalogue.

2. How APIs Work?

Client-Server Communication

When you got to a bank, the bank teller acts as an intermediary or interface between you and the bank vault. And this is the same type of relationship we see in client-server communication: The user or client makes a request to the API server, which parses the requests, queries the database, formats a response, and then sends it back.

Here is the process listed out:

  • Client sends a request to the API server
  • The API server parses that request
  • Assuming the request is formatted correctly, the server queries the database for the information or performs the action in the request
  • The server formats the response and sends it back to the client
  • The client renders the response according to its implementation

3. Internet Protocols (IPs)

Internet Protocol (IP) is the protocol for sending data from one computer to another across the internet. Each computer must have a unique IP address that identifies it from all other computers connected to the internet. It's likely that you've heard the term IP address before, even if you didn't know exactly what it meant.

There are many other internet protocols including:

  • Transmission Control Protocol (TCP) which is used for data transmission
  • Hypertext Transmission Protocol (HTTP) which is used for transmitting text and hyperlinks
  • File Transfer Protocol (FTP) which is used to transfer files between server and client

Our API will transmit data to our client via HTTP so we will primarily focus on that protocol.

4. RESTful APIs

REST stands for Representational State Transfer, which is an architectural style introduced by Roy Fielding in 2000.

Here's a short summary of the REST principles:

  • Uniform Interface: Every rest architecture must have a standardized way of accessing and processing data resources. This includes unique resource identifiers (i.e., unique URLs) and self-descriptive messages in the server response that describe how to process the representation (for instance JSON vs XML) of the data resource.
  • Stateless: Every client request is self-contained in that the server doesn't need to store any application data in order to respond to subsequent requests
  • Client-Server: There must be both a client and server in the architecture
  • Cacheable & Layered System: Caching and layering increase networking efficiency

Why RESTful are stateless?

It might appear easier to design a server that isn't stateless. There is a reason why RESTful web servers are not allowed to remember anything about the previous requests that the user has sent. In short, stateless servers make your applications scalable.

II. HTTP

1. Introduction to HTTP

Hypertext Transfer Protocol (HTTP) is a protocol that provides a standardized way for computers to communicate with each other. It has been the foundation for data communication over the internet since 1990 and is integral to understanding how client-server communication functions.

In this lesson, we'll discuss key features and elements of HTTP.

Features:

  • Connectionless: When a request is sent, the client opens the connection; once a response is received, the client closes the connection. The client and server only maintain a connection during the response and request. Future responses are made on a new connection.
  • Stateless: There is no dependency between successive requests.
  • Not Sessionless: Utilizing headers and cookies, sessions can be created to allow each HTTP request to share the same context.
  • Media Independent: Any type of data can be sent over HTTP as long as both the client and server know how to handle the data format. In our case, we'll use JSON.

Elements: Universal Resource Identifiers (URIs): An example URI is example.com/tasks/term=homework. It has certain components:

  • Scheme: specifies the protocol used to access the resource, HTTP or HTTPS. In our example http.
  • Host: specifies the host that holds the resources. In our example example.com.
  • Path: specifies the specific resource being requested. In our example, /tasks.
  • Query: an optional component, the query string provides information the resource can use for some purpose such as a search parameter. In our example, /term=homework.

Side Note: URI vs URL You may be unsure what the difference is between a URI (Universal Resource Identifier) and a URL (Universal Resource Locator). These terms tend to get confused a lot, and are even frequently used interchangeably—but there is a distinction.

The term URI can refer to any identifier for a resource—for example, it could be either the name of a resource or the address of a resource (since both the name and address are identifiers of that resource). In contrast, URL only refers to the location of a resource—in other words, it only ever refers to an address.

So, "URI" could refer to a name or an address, while "URL" only refers to an address. Thus, URLs are a specific type of URI that is used to locate a resource on the internet when a client makes a request to a server.

2. HTTP Requests

HTTP Requests HTTP requests are sent from the client to the server to initiate some operation. In addition to the URL, HTTP requests have other elements to specify the requested resource.

Elements:

  • Method: Defines the operation to be performed
  • Path: The URL of the resource to be fetched, excluding the scheme and host
  • HTTP Version
  • Headers: optional information, such as Accept-Language
  • Body: optional information, usually for methods such as POST and PATCH, which contain the resource being sent to the server

HTTP Request Methods Different request methods indicate different operations to be performed. It's essential to attend to this to correctly format your requests and properly structure an API.

  • GET: ONLY retrieves information for the requested resource of the given URI
  • POST: Send data to the server to create a new resource.
  • PUT: Replaces all of the representation of the target resource with the request data
  • PATCH: Partially modifies the representation of the target resource with the request data
  • DELETE: Removes all of the representation of the resource specified by the URI
  • OPTIONS: Sends the communication options for the requested resource

3. HTTP responses

After the request has been received by the server and processed, the server returns an HTTP response message to the client. The response informs the client of the outcome of the requested operation.

Elements:

  • Status Code & Status Message
  • HTTP Version
  • Headers: similar to the request headers, provides information about the response and resource representation. Some common headers include:
            + Date
        + Content-Type: the media type of the body of the request
  • Body: optional data containing the requested resource

III. TDD for APIs

Test-Driven Development (or TDD) is a software development paradigm used very commonly in production. It is based on a short, rapid development cycle in which tests are written before the executable code and constantly iterated on.

  • Write a test for specific application behavior.
  • Run the tests and watch them fail.
  • Write code to execute the required behavior.
  • Test the code and rewrite it as necessary to pass the test
  • Refactor your code.
  • Repeat - write your next test.

Status Codes: As an API developer, it's important to send the correct status code. As a developer using an API, the status codes—particularly the error codes—are important for understanding what caused an error and how to proceed.

Codes fall into five categories:

  • 1xx Informational
  • 2xx Success
  • 3xx Redirection
  • 4xx Client Error
  • 5xx Server Error

Common Codes:

  • 200: OK
  • 201: Created
  • 304: Not Modified
  • 400: Bad Request
  • 401: Unauthorized
  • 404: Not Found
  • 405: Method Not Allowed
  • 500: Internal Server Error

IV. API documentation

Good API documentation Good API documentation allows any developer considering the API to quickly understand the purpose of the API, the data it works with, and how to send requests and parse the responses. Some documentation, particularly for large projects, even host samples you can run within the documentation to see the API in action. For the purposes of this course, you don't need to implement interactivity, but you will provide examples that can be run by someone viewing your documentation.

Here's a recap (for your reference) of the components that are typically included in the good API documentation:

  • Introduction

  • Getting Started

              + Base URL
          + API Keys /Authentication (if applicable)

  • Errors

              + Response codes
          + Messages
          + Error types
  • Resource endpoint library
              + Organized by resource
          + Include each endpoint
          + Sample request
          + Arguments including data types
          + Response object including status codes and data types

Project Document All good, well-documented projects have a README.md file that should clearly explain the project and how to get started with it to any developers who may want to use or contribute to the project. Depending on your personal style preferences and project type, the structure and exact contents will differ, but the structure below is a good starting place.

Project Title

  • Description of project and motivation
  • Screenshots (if applicable), with captions
  • Code Style if you are following particular style guides

Getting Started

  • Prerequisites & Installation, including code samples for how to download all pre-requisites
  • Local Development, including how to set up the local development environment and run the project locally

  • Tests and how to run them

  • API Reference. If the API documentation is not very long, it can be included in the README

  • Deployment (if applicable)
  • Authors
  • Acknowledgments
APIsrestfulWeb API