How to evaluate an API: Starz

Published on by Steve Mathias

What is an API?

An Application Programming Interface, or API, is a set of commands, utilities, functions, or uniform data access points that allows for programmatic access to a system.

A website-based API is built primarily using a Simple Object Access Protocol (SOAP) or Representational State Transfer (REST) interface. While SOAP is common in older applications, new designs favor using a REST API to support simpler programmatic access by returning either XML or JSON. These APIs  allow some authenticated read/write access, and almost all of them support some form of unauthenticated read-access to a site. This is useful in the development of sites in AngularJS, other JavaScript libraries, or in the development of native mobile and desktop applications.

As APIs gain popularity and use across the web, Crowd Favorite has been at the forefront. Working with our clients to evaluate, consume, and create custom interfaces; and, supporting the expanding methods by which users interact with our clients' sites and the internet.

Evaluating an API

In anything involving an API, as with any software endeavor, the design phase is critical to the long-term success of the project. During this time, we review given resources for the site and compare that with existing API endpoints and data sources to identify that all of the required data, access, and components are available to meet the needs of the application. In our ongoing work with the Starz Entertainment team, we developed a process through design to evaluate our data sources and communicate our needs and expectations to deliver a high-performance website built against their internal content management system (CMS) using the AngularJS framework.

Review the Application Design

To determine what we required from their API, we first had to review the site design and identify distinct features, including both data and behavior, that were represented in the static designs provided by the client. It's important to focus on cases where similar information may be presented in a variety of formats and to look for cases where similar lists or items are filtered, restricted, or sorted based on user behaviors. In the beginning of the process, we also review components that look the same but display different data so that we can better come up with an architecture that divorces the display of data from the data itself. This requires being able to translate data from different responses into a single, unified format that displays code without relying on the API itself to return all objects with a unified form.\

With the Starz project, some of the more common examples of endpoints include:

  • Navigation menus
  • Movies, including genres
  • Original shows, including their own subsites
  • Search
  • Channel schedules

For other projects, such as eCommerce, we might look for other methods and data such as cart, checkout, and billing related endpoints.

During this phase, it is important to also document any data required for features beyond access points. With Starz Entertainment, this included identifying sources for responsive images, client-generated markup and text, and information necessary to link additional resources on given items.

Review Available API Methods

Using documentation provided by the Starz Entertainment team, and by exploring endpoints ourselves, we create a document mapping API endpoints to identify site features. During this time, we identified the methods are supported in the API and the endpoints that provided all of the data needed for that feature.

In the event that any endpoint does not fully and clearly support all of the data and interaction expected of it, we document the requirements that are missed, in detail,  and communicate them to the client. The sooner we achieve this, the better chance of success we have on accurately scoping, estimating, and completing the project in a given time.

When possible, it is also to our benefit to document endpoints and data that are not used from the API when developing the application. Sometimes this will result in identifying features that may have been missed, or in other cases, it may allow the API developers to trim some of the code and data which will improve its performance and the performance of our application.