Skip to main content
  • ABOUT
  • CASELAW
  • GALLERY
  • LOG IN
  • FOR COURTS
  • CONTACT
Documentation / Learning Tracks / API Learning Track / Beginner's Introduction to APIs
    • For Researchers
        • How do you want to access caselaw data?
          • Bulk Downloads
          • API
        • What level of access do you need?
        • How do I register?
        • How do I apply for researcher access?
          • Important Caveats
          • Eligibility
          • Where do I apply?
            • Harvard
            • Other Institutions
            • Others
    • For Courts
        • Digital-First Guidelines
            • Introduction
            • Digital-first publishing guidelines
              • Essential characteristics
                • Online
                • Free & Open
                • Comprehensive
                • Official
                • Citable
                • Machine Readable
              • Desirable characteristics
                • Digitally Signed
                • Versioning
                • Structured Data
                • Medium-Neutral
                • Archives
                • Search
                • Bulk
                • API
        • Case Studies
            • Case study: Arkansas
            • Case study: Canada
            • Case study: New Mexico
    • For Libraries
    • Registration
    • Search
        • Overview
        • What's included?
        • Searching in CAP is simple
          • First: Choose What To Search
          • Second: Select Your Search Criteria
          • Third: Execute the Search
        • Full-Text Case Search
          • Phrase Search
          • Exclusion
        • Tips
        • Getting Legal Help
    • API
        • API Learning Track
        • Authentication
          • Get an API Key
          • Modify The Request Headers
          • Example
          • Failure: error_auth_required
          • Browsable API
          • Sitewide Token Authentication
        • Case Text Formats
        • Pagination and Counts
          • Example
        • Endpoints
          • API Base
          • Cases Endpoint
            • Endpoint Parameters
            • Single Case Endpoint
            • Search Syntax
            • Examples
          • Reporters Endpoint
            • Endpoint Parameters
            • Examples
          • Jurisdictions Endpoint
            • Endpoint Parameters
          • Courts
            • Endpoint Parameters
          • Volumes
            • Endpoint Parameters
          • Ngrams
            • Endpoint Parameters
            • Examples
          • Citations
            • Endpoint Parameters
    • Bulk Data
        • Access Limits
        • Downloading
        • API Equivalence
        • Data Format
        • Using Bulk Data
        • Other repositories
    • Historical Trends
        • Start Here
        • Reading Results
          • Key
          • Horizontal axis
          • Vertical axis
        • Customize
          • Percentage Count/Instance Count/Scaling
          • Smoothing
        • Table view
        • Keyboard navigation
        • Download
        • Wildcard search
        • Jurisdiction search
        • Jurisdiction codes
        • Citation feature
    • API Learning Track
        • Intro to APIs
        • CAP API Tutorial
            • Intro: Browsable API
            • Intro to JSON
            • curl
            • Overview of the endpoints
            • Dig-in With Real Queries
            • Next Steps
            • Wrap-up
        • CAP API In Depth
            • Getting Started
              • Making Basic Queries
              • Filtering
              • Search
                • Full-text Search
                • Filtering by Groups or Ranges
              • Sorting
              • Types of Data You Can Query
            • Getting Full Case Text
            • Authentication
              • Find your API Key
              • Modify Your Headers
                • curl
                • python requests library
                • Other Environments
              • Doesn't work?
                • error_auth_required
                • error_limit_exceeded
            • Data Formats
              • Structured Casebody Text
            • Other Endpoints
    • Access Limits
        • Exceptions
        • Open Jurisditions
        • Research Access
        • Commercial Licensing
        • User Types and Permissions
          • Unregistered Users
          • Registered Users
          • Researchers
          • Commercial Users
    • Stability and Changes
    • Reporting Problems
        • Misspelled Words
        • Website Errors
        • Metadata Errors
    • Documentation Glossary
        • API
        • Character
        • Special Character
        • Command Line
        • curl
        • Endpoint
        • Jurisdiction
        • OCR
        • RESTful
        • Reporter
        • Server
        • Slug
        • String
        • Top-Level Domain
        • URL
        • URL Parameter
        • URL Path
        • Open Jurisdiction
        • Restricted Jurisdiction
        • Cursor
    • Data Specifications
        • Bulk
          • Structure
          • Data Format
        • API
          • Individual Records
          • Query Results
        • Individual Objects
          • Case
            • Casebody
            • Analysis Fields
          • Jurisdiction
          • Court
          • Volume
          • Reporter
          • Citation
          • Ngrams
    • Changelog
        • August 28 2020
        • August 2020
        • June 2020
        • April 2020
        • March 2020
        • February 2020
        • January 24, 2020
        • January 19, 2020
        • January 16, 2020
        • January 9, 2020
        • December 6, 2019
        • October 1, 2019
        • July 31, 2019
        • June 19, 2019

Are you a little lost in all the technical jargon, but still want to give the API a shot? This is a good place to start! This is by no means a complete introduction to APIs, but it might be just enough to help situate a technically inclined person who's a bit outside of their comfort zone. If you'd prefer to just access the cases using a human-centric interface, please check out our search tool.

Fundamentally, an API is no different from a regular website: A program on your computer, such as a web browser or curl, sends a bit of data to a server, and the server processes that data and sends a response. If you know how to read a url, you can interact with web-based services in ways that aren't limited to clicking on the links and buttons on the screen.

Consider the following url, which will perform a google search for the word "CAP."

https://www.google.com/search?q=CAP

Let's break it down into its individual parts:

https://

This first part tells your web browser which protocol to use: this isn't very important for our purposes, so we'll ignore it.

www.google.com

The next part is a list of words, separated by periods, between the initial double-slash, and before the subsequent single slash. Many people generically refer to this as the domain, which is only partly true, but the reason why that's not entirely true isn't really important for our purposes; the important consideration here is that it points to a specific server, which is just another computer on the internet.

/search

The next section, which is comprised of everything between the slash after the server name and the question mark, is called the path. It's called a path because, in the earlier days of the web, it was a 'path' through folders/directories to find a specific file on the web server. These days, it's more likely that the path will point to a specific endpoint.

You can think of an endpoint as a distinct part of a program, which could require specific inputs or provide different results. For example, the "login" endpoint on a website might accept a valid username and a password for input, and return a message that you've successfully logged in. A "register" endpoint might accept various bits of identifying information, and return a screen that says your account was successfully registered.

Though there is only one part of this particular path, search, developers usually organize paths into hierarchical lists separated by slashes. Hypothetically, if the developers at Google decided that one generalized search endpoint wasn't sufficiently serving people who wanted to search for books or locations, they could implement more specific endpoints such as /search/books and /search/locations.

?q=CAP

The final section of the URL is where you'll find the parameters, and is comprised of everything after the question mark. Parameters are a way of passing individual, labelled pieces of information to the endpoint to help it perform its job. In this case, the parameter tells the /search endpoint what to search for. Without this parameter, the response wouldn't be particularly useful.

A URL can contain many parameters, separated by ampersands, but in this instance, there is only one parameter: the rather cryptically named "q," which is short for "query," which has a value of "CAP." Parameter names are arbitrary — Google's developers could just as easily have set the parameter name to ?query=CAP, but decided that "q" would sufficiently communicate its purpose.

The Google developers designed their web search endpoint to accept other parameters, too. For example, there is an even more cryptically named parameter, 'tbs' which will limit the age of the documents returned in the search results. The parameters ?q=CAP&tbs=qdr:y will perform a web search for "CAP" and limit the results to documents less than a year old.

OK! That about does it for our beginner's introduction to web-based APIs.

You can apply all of these principles to the Caselaw Access Project API. To find out how, check out our API tutorial. Or, if you're feeling confident enough, jump right into out our In-Depth Tutorial and get to work.

Thanks, and good luck!

  • Find what you were looking for?

    If you have suggestions for improving this documentation, let us know!

Beginner's Introduction to APIs

This is our absolute beginner's tutorial on using RESTful APIs. Though we are primarily interested in educating future CAP users, this knowlege is not CAP-specific; it can be applied to many other APIs.

©2021 The President and Fellows of Harvard University. Site text is licensed CC BY-SA 4.0. Source code is MIT licensed. Harvard asserts no copyright in caselaw retrieved from this site.

  • TERMS
  • PRIVACY
  • ACCESSIBILITY