My API Writing Sample - ebrookswrites/api_documentation_writing_sample GitHub Wiki

About This Sample

This document serves as a technical writing portfolio sample for E. Brooks, demonstrating the ability to create clear and structured API documentation.

It provides an overview of the Stripe API, including:

  • Authentication methods
  • Error handling
  • A sample API request for retrieving an account balance

This example follows best practices in API documentation, using standard formatting, code snippets, and explanations to ensure ease of use for developers. While this is a simplified guide, it reflects the approach used in real-world API documentation.

For official documentation, visit Stripe API Docs.

Sample Stripe API Documentation

Introduction to the Stripe API

The Stripe API is a payment processing platform that enables businesses to handle online transactions securely and efficiently. It provides a seamless way to integrate payment services into websites and applications.

Key Features

  • RESTful Architecture – Built on REST principles, ensuring a predictable and consistent API experience.
  • Resource-Oriented URLs – Uses structured, intuitive endpoints to represent objects like payments, customers, and invoices.
  • Form-Encoded Requests – Accepts input in form-encoded format for seamless data transmission.
  • JSON Responses – Returns structured responses in JSON format for easy parsing and integration.
  • Standard HTTP Methods & Status Codes – Supports GET, POST, DELETE, and other HTTP verbs, along with standard response codes.
  • Test Mode for Safe Development – Provides a Test Mode to simulate transactions without affecting live data or financial networks.
  • Secure Authentication – Uses API keys for authentication in both Live and Test modes, ensuring secure access.

How to Connect to the Stripe API

1. Create an Account

  • Register for an account on Stripe.
  • Log in to your Stripe Dashboard.

2. Base URL

Authentication

Stripe API uses Bearer Token Authentication to authorize requests. Include your API key in the request header.

API Key Location:

  1. Log in to the Stripe Dashboard.
  2. Navigate to Developers > API Keys.
  3. Copy either:
  • Publishable Key (used in frontend implementations)
  • Secret Key (used for backend requests in Test or Live mode)

To authenticate your request, include your Secret Key as a Bearer Token in the Authorization header.

Error Handling

The Stripe API follows standard HTTP status codes to indicate the success or failure of a request:

  • 2xx Success – The request was successful.
  • 4xx Client Error – The request was invalid (e.g., missing parameters, declined payment, authentication error).
  • 5xx Server Error – A problem occurred on Stripe's end.

HTTP Status Code Summary:

Status Code Meaning Example Scenario
200 OK Success Request was processed successfully.
400 Bad Request Client Error A required parameter is missing.
401 Unauthorized Authentication Error Invalid or missing API key.
402 Payment Required Payment Error The card was declined.
403 Forbidden Permission Error API key does not have access.
404 Not Found Resource Error The requested object does not exist.
409 Conflict Conflict The request conflicts with another request.
429 Too Many Requests Rate Limit Exceeded Too many API calls in a short period. Consider exponential backoff.
500, 502, 503, 504 Server Errors An internal Stripe error occurred.

Example Error Response:

If a required parameter is missing, the API returns an error like this:

{ "error": { "type": "invalid_request_error", "message": "Missing required param: amount", "param": "amount", "code": "parameter_missing" } }

Troubleshooting Errors

The Stripe client libraries include information on errors, which will be referenced in the return code.

Example: # Select a client library to see examples of # handling different kinds of errors.

Example API Function: Retrieve Account Balance

The Stripe Balance API allows users to retrieve their account balance, including available and pending funds.

Endpoint

GET {{baseUrl}}/v1/balance

Note: This endpoint retrieves the balance of a Stripe account, not a credit card's available balance.

Example Response Code 200: Ok Get Balance Function:

{ "object": "balance", "available": [ { "amount": 0, "currency": "usd", "source_types": { "card": 0 } } ], "livemode": false, "pending": [ { "amount": 0, "currency": "usd", "source_types": { "card": 0 } } ] }

Next Steps

With a basic understanding of how to connect to the Stripe API, authenticate requests, and handle errors, here are some recommended next steps:

  • Explore Additional Endpoints – Try using other API functions such as creating a charge, retrieving customer details, or handling refunds.
  • Test in a Development Environment – Use Stripe's Test Mode before deploying live transactions.
  • Read the Official Documentation – For more details, check the Stripe API Documentation.

Additional Resources

For further questions, refer to Stripe’s developer resources or API reference: