csvbase is a simple website for sharing table data. Join the discord.

calpaterson / onion-vox-pops

approx. 23,095 rows, last changed 1 year ago
Download as csv
Make a copy

Table of contents

  1. The basics: auth and content negotations
    1. Authentication
    2. Content negotiation
  2. The API: endpoint-by-endpoint
    1. Tables
      1. Reading a table
    2. Rows
      1. Creating a new row
      2. Reading a row
      3. Updating an existing row
      4. Deleting a row

The basics: auth and content negotiation

Authentication

With CSVBase, you authenticate using by putting your username and API key straight in the url (known as "HTTP "basic" auth").

Here's an example:

https://<some_user>:<some_api_key>@csvbase.com/calpaterson/onion-vox-pops

Basic auth is widely supported and is usually accepted anywhere that accepts urls.

However, calpaterson/onion-vox-pops is public so auth is needed only for writes.

Content negotiation

CSVBase APIs use content negotiation to decide what formats are in use. This means it consults HTTP headers to decide what format to send back in response to a request.

It important that you set the Content-Type and Accept headers to be the mimetype you want: typically that is application/json for both. If you fail to include these headers in your requests, the API will still work but CSVBase will pick a sensible default: CSV for tables, JSON for rows.

You can bypass content negotiation for read-only requests by appending a file extension to the url, eg .json. Here's an example of that (same resource as above):

https://<some_user>:<some_api_key>@csvbase.com/calpaterson/onion-vox-pops.json

This is useful when dealing with software where you aren't able to set headers.

The API: endpoint-by-endpoint

There are three kinds of thing in csvbase:

  1. users
  2. tables
  3. rows

While there's no API for users so far, there is for tables and rows.

Tables

This table looks like this in JSON: 

{
    "name": "onion-vox-pops",
    "is_public": true,
    "caption": "",
    "licence": null,
    "created": "2023-09-28T10:39:12.433769+01:00",
    "last_changed": "2023-09-28T10:39:12.433769+01:00",
    "columns": [
        {
            "name": "csvbase_row_id",
            "type": "integer"
        },
        {
            "name": "article_id",
            "type": "integer"
        },
        {
            "name": "headline",
            "type": "string"
        },
        {
            "name": "description",
            "type": "string"
        },
        {
            "name": "name",
            "type": "string"
        },
        {
            "name": "quote",
            "type": "string"
        },
        {
            "name": "occupation",
            "type": "string"
        },
        {
            "name": "picture_url",
            "type": "string"
        },
        {
            "name": "page_url",
            "type": "string"
        },
        {
            "name": "date",
            "type": "string"
        },
        {
            "name": "picture_category",
            "type": "string"
        }
    ],
    "approx_size": 23095,
    "page": {
        "rows": [
            {
                "row": {
                    "article_id": 1819558790,
                    "headline": "The Not-So-Friendly Skies",
                    "description": "Last month's mysterious crash of TWA Flight 800 near Long Island, which came on the heels of several other major air tragedies, has sparked a national debate about the safety and security of commercial airlines. What do you think?",
                    "name": "Nathan Reynolds",
                    "quote": "I realize passengers are concerned, but speaking as a pilot, there's no better place to drop acid than 40,000 feet in the air.",
                    "occupation": "Pilot",
                    "picture_url": "https://i.kinja-img.com/gawker-media/image/upload/s--JQDCnwRR--/c_fill,f_auto,fl_progressive,g_center,h_200,q_80,w_200/qqp49mbqhsj0xgjes6si.jpg",
                    "page_url": "https://www.theonion.com/the-not-so-friendly-skies-1819558790",
                    "date": "1996-08-07",
                    "picture_category": "7"
                },
                "row_id": 1,
                "url": "https://csvbase.com/calpaterson/onion-vox-pops/rows/1"
            }
        ],
        "previous_page_url": null,
        "next_page_url": "https://csvbase.com/calpaterson/onion-vox-pops?op=gt&n=1"
    }
}

Note that there is the top-level metadata, plus a "page" of rows. Tables are often (usually) too big to be put into a single JSON object so they are "paginated". To follow the table, page by page, you can use the next_page_url and previous_page_url dictionary keys. They will be null if you've reached the end or are at the beginning, respectively.

Reading a table

GET from https://csvbase.com/calpaterson/onion-vox-pops

You'll need to follow the next_page_url urls (described above) to get to the end of the table.

Rows

Rows from calpaterson/onion-vox-pops look like this in JSON: 

{
    "row": {
        "article_id": 1819558790,
        "headline": "The Not-So-Friendly Skies",
        "description": "Last month's mysterious crash of TWA Flight 800 near Long Island, which came on the heels of several other major air tragedies, has sparked a national debate about the safety and security of commercial airlines. What do you think?",
        "name": "Nathan Reynolds",
        "quote": "I realize passengers are concerned, but speaking as a pilot, there's no better place to drop acid than 40,000 feet in the air.",
        "occupation": "Pilot",
        "picture_url": "https://i.kinja-img.com/gawker-media/image/upload/s--JQDCnwRR--/c_fill,f_auto,fl_progressive,g_center,h_200,q_80,w_200/qqp49mbqhsj0xgjes6si.jpg",
        "page_url": "https://www.theonion.com/the-not-so-friendly-skies-1819558790",
        "date": "1996-08-07",
        "picture_category": "7"
    },
    "row_id": 1,
    "url": "https://csvbase.com/calpaterson/onion-vox-pops/rows/1"
}

Creating a new row

POST to https://<some_user>:<some_api_key>@csvbase.com/calpaterson/onion-vox-pops/rows/

Example body
{
    "row": {
        "article_id": 1819558790,
        "headline": "The Not-So-Friendly Skies",
        "description": "Last month's mysterious crash of TWA Flight 800 near Long Island, which came on the heels of several other major air tragedies, has sparked a national debate about the safety and security of commercial airlines. What do you think?",
        "name": "Nathan Reynolds",
        "quote": "I realize passengers are concerned, but speaking as a pilot, there's no better place to drop acid than 40,000 feet in the air.",
        "occupation": "Pilot",
        "picture_url": "https://i.kinja-img.com/gawker-media/image/upload/s--JQDCnwRR--/c_fill,f_auto,fl_progressive,g_center,h_200,q_80,w_200/qqp49mbqhsj0xgjes6si.jpg",
        "page_url": "https://www.theonion.com/the-not-so-friendly-skies-1819558790",
        "date": "1996-08-07",
        "picture_category": "7"
    }
}
Example response
{
    "row": {
        "article_id": 1819558790,
        "headline": "The Not-So-Friendly Skies",
        "description": "Last month's mysterious crash of TWA Flight 800 near Long Island, which came on the heels of several other major air tragedies, has sparked a national debate about the safety and security of commercial airlines. What do you think?",
        "name": "Nathan Reynolds",
        "quote": "I realize passengers are concerned, but speaking as a pilot, there's no better place to drop acid than 40,000 feet in the air.",
        "occupation": "Pilot",
        "picture_url": "https://i.kinja-img.com/gawker-media/image/upload/s--JQDCnwRR--/c_fill,f_auto,fl_progressive,g_center,h_200,q_80,w_200/qqp49mbqhsj0xgjes6si.jpg",
        "page_url": "https://www.theonion.com/the-not-so-friendly-skies-1819558790",
        "date": "1996-08-07",
        "picture_category": "7"
    },
    "row_id": 1,
    "url": "https://csvbase.com/calpaterson/onion-vox-pops/rows/1"
}

Status code 201 upon success.

Reading a row

GET from https://csvbase.com/calpaterson/onion-vox-pops/rows/1

No body is provided with this request. Status code 200 upon success.

Example response
{
    "row": {
        "article_id": 1819558790,
        "headline": "The Not-So-Friendly Skies",
        "description": "Last month's mysterious crash of TWA Flight 800 near Long Island, which came on the heels of several other major air tragedies, has sparked a national debate about the safety and security of commercial airlines. What do you think?",
        "name": "Nathan Reynolds",
        "quote": "I realize passengers are concerned, but speaking as a pilot, there's no better place to drop acid than 40,000 feet in the air.",
        "occupation": "Pilot",
        "picture_url": "https://i.kinja-img.com/gawker-media/image/upload/s--JQDCnwRR--/c_fill,f_auto,fl_progressive,g_center,h_200,q_80,w_200/qqp49mbqhsj0xgjes6si.jpg",
        "page_url": "https://www.theonion.com/the-not-so-friendly-skies-1819558790",
        "date": "1996-08-07",
        "picture_category": "7"
    },
    "row_id": 1,
    "url": "https://csvbase.com/calpaterson/onion-vox-pops/rows/1"
}

Updating an existing row

PUT to https://<some_user>:<some_api_key>@csvbase.com/calpaterson/onion-vox-pops/rows/1

Example body
{
    "row": {
        "article_id": 1819558790,
        "headline": "The Not-So-Friendly Skies",
        "description": "Last month's mysterious crash of TWA Flight 800 near Long Island, which came on the heels of several other major air tragedies, has sparked a national debate about the safety and security of commercial airlines. What do you think?",
        "name": "Nathan Reynolds",
        "quote": "I realize passengers are concerned, but speaking as a pilot, there's no better place to drop acid than 40,000 feet in the air.",
        "occupation": "Pilot",
        "picture_url": "https://i.kinja-img.com/gawker-media/image/upload/s--JQDCnwRR--/c_fill,f_auto,fl_progressive,g_center,h_200,q_80,w_200/qqp49mbqhsj0xgjes6si.jpg",
        "page_url": "https://www.theonion.com/the-not-so-friendly-skies-1819558790",
        "date": "1996-08-07",
        "picture_category": "7"
    },
    "row_id": 1,
    "url": "https://csvbase.com/calpaterson/onion-vox-pops/rows/1"
}
Response

Upon success the body you sent will be echoed back, with status code 200.

Deleting a row

DELETE from https://<some_user>:<some_api_key>@csvbase.com/calpaterson/onion-vox-pops/rows/1

No body is required. Status code 204 upon success.