Reorganize Anteater API docs (#33)

laggycomputer · web-flow · commit dbfce30d03f2 · 2024-12-26T20:51:17.000-05:00
* docs: 📚️ [api] api is maintained by a specifc arm of ICSSC * docs: 📚️ [api] redo "what is ICSSC" defer to club events page about event times, make some mildly opinionated tweaks * docs: 📚️ [api] link attribution from about * docs: 📚️ [api] tighten language about research data * docs: 📚️ [api] historical data info out of accordions, reword * docs: 📚️ [api] reword inviting non-projects people * docs: 📚️ [api] link to contributor docs will fill out said contributor docs * docs: 📚️ [api] import anteater-api/CONTRIBUTING.md * docs: 📚️ [api] mention docker compose is not strictly needed * docs: 📚️ [api] contrib guide clarity * docs: 📚️ [api] reorder contrib landing, language tweak * docs: 📚️ [api] about api at index.md * docs: 📚️ [api] move attribution to about section this requires chair approval * docs: 📚️ [api] fix 404 on dev landing * docs: 📚️ [api] add one linebreak * docs: 📚️ [api] link dev docs to about * docs: 📚️ [api] clarify anteater offers both rest and gql * docs: 📚️ [api] example of REST resource, whitespace * docs: 📚️ [api] clarify what gql is, whitespace * docs: 📚️ [api] new getting started page, move some content onto it * docs: 📚️ [api] finish dev getting started * docs: 📚️ [api] best practices -> "keys and limits" * docs: 📚️ [api] keys page whitespace * docs: 📚️ [api] grammar * docs: 📚️ [api] per-key ratelimit clarification * docs: 📚️ [api] how to use api keys also whitespace * docs: 📚️ [api] clarify requests is a python lib * docs: 📚️ [api] clarify in snippets any endpoint is ok * docs: 📚️ [api] as of node 18 importing fetch is unnecessary everywhere * docs: 📚️ [api] attribution policy back in dev docs sidebar * docs: 📚️ [api] state graphql url * docs: 📚️ [api] tighter language * docs: 📚️ [api] link to gh when we say FOSS how did we never do this before * docs: 📚️ [api] shorten contrib setup title * docs: 📚️ [api] use <Step> for contrib setup steps * docs: 📚️ [api] wording tweak * docs: 📚️ [api] page descriptions * docs: 📚️ [api] move attribution to developer category #33 (comment) * docs: 📚️ [api] title case in title * docs: 📚️ [api] description tweak
diff --git a/content/docs/about/anteaterapi.mdx b/content/docs/about/anteaterapi.mdx
diff --git a/content/docs/about/anteaterapi/index.md b/content/docs/about/anteaterapi/index.md
@@ -0,0 +1,42 @@
+---
+title: Anteater API
+description: Basic information about Anteater API
+---
+
+## What is Anteater API?
+
+Anteater API provides various data from the University of California, Irvine, in a structured format that can be used by other software.
+
+Anteater API is maintained by its team within the Projects Committee of the ICS Student Council (ICSSC).
+
+## What is ICSSC?
+
+ICS Student Council is a far-reaching organization that aims to improve student life within and beyond the Donald Bren School of Information and Computer Sciences.
+
+Feel free to join us at our [events](https://icssc.club/events). All UCI affiliates are welcome.
+
+Learn more about how you can get involved with us [here](https://icssc.club/get-involved).
+
+## Using Anteater API in Your Software
+
+If you're building an application that manipulates public data provided by the school, the Anteater API likely has you covered.
+
+You can learn about the capabilities of Anteater API, and how to use it, [here](/docs/developer/anteaterapi).
+
+Any use of Anteater API for any purpose is bound by the [attribution policy](/docs/developer/anteaterapi/attribution-policy).
+
+## Using Anteater API for Research
+
+Anteater API contains a wealth of historical data of potential research interest. The following is a non-exhaustive list of historical data we serve:
+
+- **Schedule of Classes** for terms not earlier than fall 1990.
+- **Letter grade distributions** for course offerings not earlier than summer 2014.
+- **Course enrollment trends** for course sections held not earlier than winter 2022.
+
+If there's more publicly available data that you'd like to see us provide for research, please don't hesitate to reach out.
+
+## Contributing to Anteater API
+
+Anteater API is free and open-source software (FOSS). The word "free" in this context is as in free speech, though there is also no monetary cost to use Anteater API. This means that everyone can view its [source code](https://github.com/icssc/anteater-api) to see how it works, and everyone is allowed to contribute to Anteater API and/or redistribute its source code.
+
+For more information on contributing to Anteater API, see the [contributor section](/docs/contributor/anteaterapi) of the Anteater API documentation.
diff --git a/content/docs/contributor/anteaterapi/index.md b/content/docs/contributor/anteaterapi/index.md
@@ -1,3 +1,7 @@
 ---
 title: Anteater API
 ---
+
+To learn how to set up a development environment for Anteater API, see the [setup guide](/docs/contributor/anteaterapi/setup).
+
+The Anteater API team may invite active contributors to join the team if they are not already part of the ICSSC Projects Committee.
diff --git a/content/docs/contributor/anteaterapi/setup.mdx b/content/docs/contributor/anteaterapi/setup.mdx
@@ -0,0 +1,84 @@
+---
+title: Setting Up
+description: How to set up a local Anteater API environment to contribute
+---
+
+import { Step, Steps } from 'fumadocs-ui/components/steps';
+
+Thank you for your interest in contributing to Anteater API!
+
+## ✅ Getting Started
+
+### 🛠️ Prerequisites
+
+- For Windows users: A [Windows Subsystem for Linux](https://learn.microsoft.com/en-us/windows/wsl/install) instance
+- A Node.js environment
+- [pnpm](https://pnpm.io/installation), a blazingly fast package manager for Node.js
+- [nvm](https://github.com/nvm-sh/nvm?tab=readme-ov-file#install--update-script), a version manager for Node.js
+- [Docker Compose](https://docs.docker.com/compose/install/) for running the local database server, or an already running PostgreSQL server
+- Optionally: [PostgreSQL](https://www.postgresql.org/download/) version 16, for generating database dumps
+
+### 🧑‍💻 Setting Up
+
+<Steps>
+
+<Step>
+Clone the repository and change into it. In your command line:
+
+   ```shell
+   git clone git@github.com:icssc/anteater-api.git
+   cd anteater-api
+   ```
+</Step>
+
+<Step>
+Make a copy of the `.env.example`.
+
+   ```shell
+   cp .env.example .env
+   ```
+</Step>
+
+<Step>
+Install the dependencies.
+
+   ```shell
+   pnpm i
+   ```
+</Step>
+
+<Step>
+Download the latest version of the database dump [here](https://anteater-api-dump.s3.us-west-1.amazonaws.com/db.sql.gz), and move it into the `packages/db` directory.
+
+   _Optional_: Verify the integrity of the database dump.
+
+   To do this, download the checksum [here](https://anteater-api-dump.s3.us-west-1.amazonaws.com/db.sql.gz.sha256sum), move it into the `packages/db` directory, then run the following command:
+
+   ```shell
+   sha256sum -c db.sql.gz.sha256sum
+   ```
+
+   If the checksum does not match, the database dump may be corrupt or have been tampered with. You should delete it immediately and try downloading it again.
+</Step>
+
+<Step>
+Start the local Postgres database. If you are using Docker Compose, as we recommend above, this is simple:
+
+   ```shell
+   docker-compose up -d
+   ```
+</Step>
+
+<Step>
+Start the development server.
+
+   ```shell
+   pnpm dev
+   ```
+
+   The process of database seeding (importing data from the database dump) can take a while. If at first this fails, wait a few minutes before trying again.
+
+   The development server will automatically reload upon any changes to the codebase. This will aid in your testing.
+</Step>
+
+</Steps>
diff --git a/content/docs/developer/anteaterapi/getting-started.md b/content/docs/developer/anteaterapi/getting-started.md
@@ -0,0 +1,36 @@
+---
+title: Getting Started
+description: What you need to do in order to start using Anteater API
+---
+
+**This page is for Anteater API users. Potential contributors refer to the [Contributor Docs](/docs/contributor/anteaterapi).**
+
+## REST or GraphQL?
+
+The first choice you need to make when using Anteater API is between our REST API and our GraphQL API.
+The correct choice is dependent on your use case and, to some degree, on personal preference.
+It is akin to the choice of which programming language to use.
+
+## Authorization
+
+Unlike some other Web APIs, Anteater API does not require API keys or authentication, so you can start using this API immediately.
+However, there are still advantages to seeking an API key; learn how to obtain and use one [here](./keys-limits).
+
+## Choosing your stack
+
+If your application is not already fully set up to handle REST or GraphQL, you will need to add to your stack, the list of technologies powering your application.
+Examples of parts of your stack include your language (e.g. JavaScript), frameworks (e.g. React), and, most relevantly to Anteater API, your HTTP client.
+If using GraphQL, you may also want to select a specialized GraphQL client.
+
+We have a guide on integrating our REST API with TypeScript [here](/docs/developer/anteaterapi/rest-api/guides/typescript-integration).
+
+## Attribution
+
+If you use Anteater API, you **must** follow the [Attribution Policy](./attribution-policy).
+
+## Reading documentation
+
+Finally, read the API reference for [REST](https://anteaterapi.com/reference) or try the [GraphQL Sandbox](https://studio.apollographql.com/sandbox/explorer?endpoint=https://anteaterapi.com/v2/graphql).
+Both provide exhaustive documentation of what Anteater API offers.
+
+Have fun!
diff --git a/content/docs/developer/anteaterapi/graphql-api/index.mdx b/content/docs/developer/anteaterapi/graphql-api/index.mdx
@@ -3,5 +3,6 @@ title: GraphQL API
 ---
 
 The GraphQL API allows for access to the same resources that can be accessed through the REST API.
+The current URL is https://anteaterapi.com/v2/graphql.
 
 You can try using the GraphQL API through [Apollo Sandbox](https://studio.apollographql.com/sandbox/explorer?endpoint=https://anteaterapi.com/v2/graphql) (also available through the navbar), which is a lightweight web-based IDE for GraphQL queries. The Sandbox also contains up-to-date documentation on the different queries available, so you can develop and test all of your queries from within a single page.
diff --git a/content/docs/developer/anteaterapi/index.mdx b/content/docs/developer/anteaterapi/index.mdx
@@ -6,7 +6,9 @@ import { Accordion, Accordions } from "fumadocs-ui/components/accordion";
 
 Anteater API is an API maintained by ICSSC Projects that provides various UCI related data. All the data served through Anteater API is publicly accessible, or derived from historically publicly accessible data. If you use data obtained though Anteater API in your project, please give us credit in accordance with our [Attribution Policy](/docs/developer/anteaterapi/attribution-policy).
 
-You are currently reading the **Developer Docs** for Anteater API. This part of the documentation covers how to properly integrate Anteater API into your own projects. If you're a developer who's interested in helping to improve Anteater API, please refer to the Anteater API [Contributor Docs](/docs/contributor/anteaterapi/getting-started-contributor).
+You are currently reading the **Developer Docs** for Anteater API. This part of the documentation covers how to properly integrate Anteater API into your own projects.
+If you're a developer who's interested in helping to improve Anteater API, please refer to the Anteater API [Contributor Docs](/docs/contributor/anteaterapi/).
+For general introductory information about Anteater API, see the [About Docs](/docs/about/anteaterapi).
 
 ## FAQ
 
@@ -18,15 +20,21 @@ You are currently reading the **Developer Docs** for Anteater API. This part of
 
   </Accordion>
   <Accordion title="What is the difference between REST and GraphQL?">
-    REST stands for **RE**presentational **S**tate **T**ransfer. A REST API has endpoints, each of which represents a resource. When a request is made to an endpoint, the server responds with a representation of the state of the resource, hence the name. Each HTTP verb (`GET`, `POST`, etc.) represents a different action on the resource being requested.
+    Anteater API offers both a REST API and a GraphQL API.
 
-    GraphQL is a query language for APIs. It is more flexible than REST, since you can query multiple endpoints in the same request, and also include only fields from the endpoint(s) that are relevant. However, it does have a slightly higher learning curve, and may require additional work to integrate into your application.
+    REST stands for **RE**presentational **S**tate **T**ransfer. A REST API has endpoints, each of which represents a resource (e.g. which week of school a certain date is in).
+    When a request is made to an endpoint, the server responds with a representation of the state of the resource (e.g. week 4 of winter), hence the name.
+    Each HTTP verb (`GET`, `POST`, etc.) represents a different action on the resource being requested.
+
+    GraphQL is a query language for APIs. It is more flexible than REST, since you can query multiple endpoints in the same request and/or selected parts of the data (e.g. when the schedule of classes is posted for a quarter instead of all the important dates).
+    However, it does have a slightly higher learning curve, and may require additional work to integrate into your application.
 
     The correct API to use will almost always depend on your use case; there is no single correct answer.
 
   </Accordion>
   <Accordion title="How do I start using Anteater API?">
-    Unlike some other Web APIs, Anteater API does not require API keys or authentication, so you can start using this API immediately. However, in order to ensure a good experience for all users of the API, we ask that you read and abide by the [Attribution Policy](attribution-policy).
+    Take a look at the [Getting Started](./anteaterapi/getting-started) page.
+    In order to ensure a good experience for all users of the API, we ask that you read and abide by the [Attribution Policy](/docs/developer/anteaterapi/attribution-policy).
 
   </Accordion>
 </Accordions>
diff --git a/content/docs/developer/anteaterapi/keys-limits.mdx b/content/docs/developer/anteaterapi/keys-limits.mdx
@@ -1,14 +1,20 @@
 ---
-title: Best Practices
+title: Keys and Ratelimits
+description: The ratelimits on Anteater API and how to obtain and use an API key
 ---
 
 import { Tab, Tabs } from "fumadocs-ui/components/tabs";
 
 ## Rate Limits
 
-You may use most features of Anteater API without requesting an API key. Requests made without keys are subject to a per-IP basis and also draws from a global quota that is replenished on an hourly basis. If the global quota is exhausted, only requests with valid API keys will be accepted, so we recommend that you request an API key [here](https://dashboard.anteaterapi.com).
+You may use most features of Anteater API without requesting an API key.
+Requests made without keys are ratelimited on a per-IP basis and also draw from a global quota that is replenished on an hourly basis.
+If the global quota is exhausted, only requests with valid API keys will be accepted, so we recommend that you request an API key [here](https://dashboard.anteaterapi.com).
 
-Rate limits for Anteater API are enforced on a per-key basis otherwise. However, our goal with these rate limits is to support almost all applications while preventing abuse. We understand that student projects, especially those made for a hackathon, may experience sudden traffic spikes, and have ensured our rate limits are much higher than what is necessary for almost all applications. If your application requires a higher rate limit, we will evaluate your use case and may choose to increase your rate limit.
+When using a key to access Anteater API, you are bound by your own key-specific ratelimit instead of the global quota.
+Our goal with these rate limits is to support almost all applications while preventing abuse.
+We understand that student projects, especially those made for a hackathon, may experience sudden traffic spikes, and have ensured our rate limits are much higher than what is necessary for almost all applications.
+If your application requires a higher rate limit, we will evaluate your use case and may choose to increase your rate limit.
 
 With that being said, we ask that all developers refrain from purposefully sending large amounts of requests in a short interval, or making malicious requests with the intent to exploit vulnerabilities in the API. We reserve the right to blacklist IP addresses making such requests.
 
@@ -22,15 +28,17 @@ Publishable keys are intended to be used in client-side code and as such can be
 
 Secret keys are intended to be used in server-side code, and should not be exposed since no additional verification is performed.
 
-Regardless of the type of key, you'll have to send the key to the API in order to take advantage of its benefits. The following is a non-exhaustive list of code snippets for doing so using various HTTP libraries. If the library you're using isn't present below, please don't hesitate to open a pull request!
+Regardless of the type of key, you'll have to send the key to the API in order to take advantage of its benefits.
+You must provide your API key as a bearer token in your requests.
+If you don't know what that means, that's okay.
+The following is a non-exhaustive list of code snippets for doing so using common HTTP libraries.
+If the library you're using isn't present below, please don't hesitate to open a pull request!
 
-<Tabs items={["Fetch API", "Axios", "Requests"]}>
+<Tabs items={["Fetch API", "Axios", "Requests (Python)"]}>
   <Tab value="Fetch API">
     ```js
-    import fetch from "cross-fetch"; // ESM import
-    // const fetch = require("cross-fetch"); // CJS import
-
     const res = await fetch(
+      // or another endpoint
       "https://anteaterapi.com/v2/rest/websoc" +
         new URLSearchParams({
           year: "2023",
@@ -53,7 +61,7 @@ Regardless of the type of key, you'll have to send the key to the API in order t
     import axios from "axios"; // ESM import
     // const axios = require("axios"); // CJS import
 
-    const res = await axios.get("https://anteaterapi.com/v2/rest/websoc", {
+    const res = await axios.get(/* or another endpoint */ "https://anteaterapi.com/v2/rest/websoc", {
       params: {
         year: "2023",
         quarter: "Spring",
@@ -68,11 +76,12 @@ Regardless of the type of key, you'll have to send the key to the API in order t
     ```
 
   </Tab>
-  <Tab value="Requests">
+  <Tab value="Requests (Python)">
     ```py
     import requests
 
     res = requests.get(
+      # or another endpoint
       "https://anteaterapi.com/v2/rest/websoc",
       params={"year": "2023", "quarter": "Spring", "department": "COMPSCI"},
       headers={
diff --git a/content/docs/developer/anteaterapi/meta.json b/content/docs/developer/anteaterapi/meta.json
@@ -2,8 +2,9 @@
   "title": "Anteater API",
   "icon": "Workflow",
   "pages": [
+    "getting-started",
     "attribution-policy",
-    "best-practices",
+    "keys-limits",
     "api-versioning",
     "rest-api",
     "graphql-api",
diff --git a/content/docs/developer/anteaterapi/migrating.mdx b/content/docs/developer/anteaterapi/migrating.mdx
@@ -25,7 +25,7 @@ We believe that sunsetting PeterPortal API in favor of Anteater API will allow u
         Change the base URL used in your API calls to https://anteaterapi.com/v2/rest (for the REST API) or https://anteaterapi.com/v2/graphql (for the GraphQL API).
     </Step>
     <Step>
-        Optional, but highly recommended: Request an API key at https://dashboard.anteaterapi.com, and use that API key in all of your API calls. More details can be found [here](/docs/developer/anteaterapi/best-practices#using-your-api-key).
+        Optional, but highly recommended: Request an API key at https://dashboard.anteaterapi.com, and use that API key in all of your API calls. More details can be found [here](/docs/developer/anteaterapi/keys-limits#using-your-api-key).
     </Step>
     <Step>
         Read the section below that corresponds to your current usecase, and apply any modifications to your code.
