RESTful Web API Design

An API is a set of routines or functions. It’s an interface used for performing tasks, retrieving data, and manipulating data. APIs use HTTP methods, which are used on a resource to GET, POST (submit form data), PUT (for updating files), PATCH (a partial update), and DELETE.

Adding an API

  • Bolt-on strategy – when you already have an application and are adding an API to it
  • Greenfield strategy – no underlining application. There’s complete freedom and flexibility to do what you want. Generally the “API first” or “mobile first” mentality.
  • Facade strategy – wraps existing logic with replace as you go. This is ideal for legacy systems so the application is always functional.

Designing the Relationship

  • Independent – the resources may exist regardless of the other existing but they may reference each other
  • Dependent – one resource cannot exist without the parent
  • Associative – they are independent of each other but the relationship contains additional properties to describe it

Planning the Relationships

  • Ask yourself the following questions:
    • Can both resources exist without the other?
    • Does one resource only exist when the other exists?
    • Does the relationship between resources require more information than just the links between them?
  • It should be relatively easy to map out the flow, action, etc for each resource. If not, you need to revise your design.
  • Consider using notecards to write down each resource action

REST

  • REST stands for Representational State Transfer
  • It’s an architecture for designing network-based applications
  • It is not a protocol, framework, or standard

Benefits of Stateless Servers

  • Visibility – monitoring systems and developers do not need to look beyond the request to trace a bug
  • Reliability – easy to recover from system failures

Drawbacks of Stateless Servers

  • Network Bandwidth – client sends state for every request
  • Complexity – all clients must handle their states

Benefits of Caching

  • Performance – for stateless and caching, many requests do not need to go all the way to the server
  • Scalability – server gets fewer requests so it can handle more clients

Drawbacks of Caching

  • Data reliability – clients might use stale data

Facets of a Uniform Interface

  • Self descriptive messages
  • Server includes metadata, such as Content-Type, to help clients process the responses
  • Hypermedia as the engine of application state (HATEOAS)
  • Client only assumes a fixed entry-point to the API, the server tells clients all other available actions through hyperlinksBenefits of a Layered System
  • Encapsulation (simplify an interface to a legacy server)
  • Scalability (layers enable load balancing)
  • Security (add access control rules to data crossing a boundary, just like a firewall)

Drawbacks of a Layered System

  • Latency – adding layers increases latency

A Brief Overview of GraphQL

GraphQL is a query language designed to make data fetching easier. It allows you to get data from the server to the client. It is language agnostic and became open source in 2015.

Overview

  • Input types include: integer, float, string, boolean, null, enum, list, object
  • It has a built-in documentation for the schema
  • Can create operation names to help identify different queries
  • Creates changes through mutations
  • API determines what mutations are allowed

Benefits

  • Avoids multiple REST calls
  • Is backward compatible and version-free
  • Can wrap around existing APIs
  • Queries can have comments

 

Software Design Styles and the Cycle of Software Design

Recently I did some document diving to find out more about different styles of software design. When it comes to building software, I’m someone who is more familiar with getting things to work, and I haven’t focused too much attention on discussing my approaches. So in an effort to become more eloquent about the way I describe my work, I thought I’d share an overview on software design styles and the cycle of software design:

Service-oriented architecture (SOA): a style of software design where services are provided with application components through a communication protocol over a network. The elements of SOA include:

  1. Application frontend, service, service repository, service bus
  2. Contract, implementation, interface
  3. Business logic, data

A web service is an example of an SOA with a well-defined set of implementation choices.

Representational state transfer (RESTful): RESTful web services allow systems to access and manipulate web resources by using a predefined set of operations. RESTful includes the HTTP methods get, put, post, and delete. More information on what these mean include the following:

  • Get: retrieves a representation of the collection
  • Put: replaces the addressed item of a collection, or if it doesn’t exist, it creates it
  • Post: create a new entry in the collection
  • Delete: delete the item in a collection

Model-view-controller (MVC): a pattern for implementing user interfaces. It’s broken down into three components:

  • Model: directly manages the data and logic of the application
  • View: the output of the information, how the information is presented to the user
  • Controller: uses input from the user to make changes to the model or view

Software development life cycle (SDLC): a structured sequence of stages in developing a software product. These steps include: communication, requirement gathering, feasibility study, system analysis, software design, coding, testing, integration, implementation, operations & maintenance, and disposition.