API standards

Understanding API standards used in the Public APIs directory

API standards

The Public APIs directory uses a standardized format to categorize and describe APIs. Understanding these standards will help you navigate the directory and contribute new entries.

API entry format

Each API entry in the directory follows this structure:

| API | Description | Auth | HTTPS | CORS |
| --- | --- | --- | --- | --- |
| [API Title](link-to-docs) | Description of API | `apiKey` | Yes | Yes |

Column specifications

API column

• Format: [Title](URL)
• Title: The name of the API without TLD or “API” suffix
  • ✔ Correct: [Gmail](https://developers.google.com/gmail/api/)
  • ❌ Incorrect: [Gmail.com API](https://developers.google.com/gmail/api/)
• URL: Must link to the official API documentation

Description column

• First character: Must be capitalized
• Length: Maximum 100 characters
• Ending: Should not end with punctuation (., !, ,, etc.)
• Content: Clear, concise description of what the API does

Auth column

• Purpose: Indicates the authentication method required
• Format: Must be wrapped in backticks (except for No)
• Allowed values only - see Auth types section below

HTTPS column

• Purpose: Indicates if the API supports HTTPS
• Values: Yes or No
• Note: HTTPS is strongly preferred for security

CORS column

• Purpose: Indicates Cross-Origin Resource Sharing support
• Values: Yes, No, or Unknown
• Note: Without CORS, APIs are only usable server-side

Auth types

The directory recognizes the following authentication methods:

OAuth

Description: The API supports OAuth authentication

Format in table: `OAuth`

Use case: APIs that require user authorization and token-based authentication

Example:

| [GitHub](https://docs.github.com/en/rest) | GitHub API | `OAuth` | Yes | Yes |

apiKey

Description: The API uses a private key string/token for authentication

Format in table: `apiKey`

Use case: Most common authentication method where you register for an API key

Example:

| [OpenWeatherMap](https://openweathermap.org/api) | Weather data | `apiKey` | Yes | Unknown |

X-Mashape-Key

Description: The API requires a Mashape key header

Format in table: `X-Mashape-Key`

Use case: APIs hosted on RapidAPI (formerly Mashape) platform

Example:

| [Random Facts](https://rapidapi.com/...) | Random facts | `X-Mashape-Key` | Yes | Unknown |

User-Agent

Description: The API requires a User-Agent header

Format in table: `User-Agent`

Use case: APIs that require identification of the client application

Example:

| [Wikipedia](https://www.mediawiki.org/wiki/API) | Wikipedia data | `User-Agent` | Yes | Unknown |

No

Description: The API requires no authentication

Format in table: No (no backticks)

Use case: Completely open APIs with no authentication requirements

Example:

| [Dog API](https://dog.ceo/dog-api/) | Dog pictures | No | Yes | Yes |

HTTPS requirements

Why HTTPS matters

• Security: Encrypts data in transit
• Privacy: Protects user information
• Trust: Indicates professional, secure API
• Modern standard: Expected for all production APIs

HTTPS values

Value	Meaning
Yes	API supports HTTPS connections
No	API only supports HTTP (not recommended)

APIs without HTTPS support should be used with caution, especially when handling sensitive data.

CORS explanations

What is CORS?

CORS (Cross-Origin Resource Sharing) is a mechanism that allows web applications running at one origin to access resources from a different origin.

Why CORS matters

Without proper CORS configuration:

• APIs can only be called from server-side code
• Browser-based JavaScript applications will be blocked
• Client-side web applications cannot access the API directly

CORS values

Value	Meaning	Impact
Yes	API supports CORS	Can be used in browser-based apps
No	API does not support CORS	Server-side use only
Unknown	CORS support is unclear	May need testing to confirm

Testing CORS support

You can test if an API supports CORS by:

1. Making a request from a browser console
2. Checking response headers for Access-Control-Allow-Origin
3. Using online CORS testing tools

Using APIs without CORS

If an API doesn’t support CORS, you can:

• Use it from server-side code (Node.js, Python, etc.)
• Implement a proxy server to handle requests
• Use browser extensions (development only, not production)

Formatting requirements

Table spacing

• Each column must start and end with exactly 1 space
• Consistent spacing makes the table readable in Markdown

Correct:

| [API](link) | Description | `apiKey` | Yes | Yes |

Incorrect:

|[API](link)|Description|`apiKey`|Yes|Yes|

Alphabetical order

Within each category, APIs must be listed in alphabetical order by title.

Purpose: Makes it easier to:

• Find specific APIs
• Avoid duplicates
• Maintain the list

Category requirements

Each category must have:

• Minimum 3 entries - Categories with fewer entries should be merged
• Listed in Index - All categories must appear in the index section
• Clear header - Use ### followed by category name

Learn more

For detailed contribution guidelines, see:

• GitHub repository - Full contribution guide
• Validation tools - How entries are validated
• FAQ - Common questions about submissions