5  APIs for Machine Learning

An API is a set of rules that allows two applications to interact, that provides the appropriate level of abstraction to interact with the underlying (ML) functionality.

Most ML models have a simple interface for prediction, which can be encapsulated as a simple side-effect-free function. The prediction can take the shape of a boolean value or probability.

5.1 Architectural constraints

  • Client-server (separation of concerns)
  • Stateless
  • Cacheable
  • Uniform interface
    • POST: create a new resource
    • GET: retrieve a specific resource (by id) or a collection of resources
    • PUT/PATCH: update a specific resource (by id)
    • DELETE: remove a specific resource by id able to Create, Read, Update, and Delete (CRUD) resources

5.2 Best practices for RESTful APIs

  • Avoid using cryptic resource names
  • Nouns not verbs when naming resources
    • GET /users not GET /get_users
  • Plural nouns
    • GET /users/{userId} not GET /user/{userID}
  • Dashes in URIs for resources and path parameters but use underscores for query parameters
    • GET /admin-users/?find_desc=super
  • Return appropriate HTTP and informative messages to the user

5.3 Documentation

ML models to be released in production should be accompanied by documentation detailing:

  • Their intended use cases and context of use (to minimize misuse)
  • Their performance and limitations (along with details about the performance evaluation procedures)

There is no official standard for documenting ML models yet.

5.3.1 Model Cards

Model cards are short documents accompanying trained ML models that provide benchmarked evaluation in a variety of conditions.

Key information included:

  • Model details: type of model, architecture, version, etc.
  • Intended uses and limitations: potential biases and ethical considerations
  • Training parameters: hyperparameters, optimization details, etc.
  • Evaluation results: performance metrics and experimental information
  • Training datasets: which datasets were used to train the model

5.3.2 Dataset Cards

The goal is to promote responsible usage and inform users of any potential biases within the dataset.

Key information included:

  • Dataset contents: what data is included and its structure
  • Context for use: appropriate and inappropriate use cases
  • Creation process: how the data was collected and processed
  • Considerations: ethical concerns, limitations, biases, and other important factors