API Developer Onboarding

Learn to interact with APIs using cURL, parse JSON responses, authenticate with JWT tokens, and navigate API documentation to integrate third-party services. 4 steps, 25 minutes.

25 minutes 4 stepsBeginner

Key Challenge

Most new developers struggle with APIs because they skip fundamentals: making raw HTTP requests, parsing responses, understanding authentication. This workflow covers the mental model.

Make your first API request using cURL

cURL is a command-line tool to make HTTP requests. Basic syntax: curl https://api.example.com/endpoint. Example: curl https://jsonplaceholder.typicode.com/users/1 returns JSON user data. Add options: -X GET (explicit method), -H 'Content-Type: application/json' (headers), -d '{...}' (request body for POST/PUT). Example POST: curl -X POST https://api.example.com/users -H 'Content-Type: application/json' -d '{"name":"Alice"}'. Response shows status code (200=success, 401=unauthorized, 404=not found) and response body (JSON, HTML, or text). Debugging: add -v (verbose) to see full request/response including headers. Add -i (include headers) to see response headers. Common headers: Authorization: Bearer {token}, Accept: application/json. Understanding request/response cycle is fundamental: client sends HTTP request (method, URL, headers, body), server processes, returns response (status code, headers, body). Mastering cURL prepares you for programming (all languages make HTTP requests); debugging (verify API works before writing code); testing (write scripts to verify API behavior).

💡 Pro Tip: cURL in PowerShell (Windows) requires escaping quotes differently. Use single quotes for outer string: curl.exe -X GET 'https://api.example.com/users/1'. On Windows, use curl.exe explicitly (Windows comes with curl on Windows 10+).

Open cURL Tester

Parse JSON responses and understand data structures

JSON (JavaScript Object Notation) is the standard API response format. Structure: objects {...}, arrays [...], strings '...', numbers, booleans (true/false), null. Example: {"user":{"id":1,"name":"Alice","emails":["alice@example.com"]},"active":true}. Parse with jq (command-line JSON processor): curl https://api.example.com/users/1 | jq .user.name extracts 'Alice'. jq syntax: .key accesses object property, .[0] accesses array element, .[] iterates array, .[] | select(.id==1) filters. Examples: jq '.users | length' (count array elements), jq '.[] | select(.status=="active") | .email' (extract emails of active users). JSON parsing prevents mistakes: you see actual data structure instead of guessing. Common mistakes: assuming all responses are arrays (some are objects), not handling null values (crashes code), assuming all values are strings (they're not). Understanding JSON unlocks API debugging: if API fails, inspect JSON response to see error messages server sends.

💡 Pro Tip: Install jq for powerful JSON parsing: jq is easier than writing code. Example: curl api | jq '.[] | .name' extracts all names from array of objects. For complex parsing, use programming language (Python json module, JavaScript JSON.parse).

Open JSON Parser

Authenticate with JWT tokens: get token, use in Authorization header

APIs use JWT for authentication. Workflow: (1) Send login request (username, password): curl -X POST https://api.example.com/login -d '{"username":"user","password":"pass"}'. Response: {"token":"eyJhbG..."}. (2) Copy token (long string). (3) Make authenticated request: curl https://api.example.com/protected -H 'Authorization: Bearer eyJhbG...'. Server validates token signature, extracts userId, checks permissions, returns data. Token structure: header.payload.signature. Payload is base64-encoded JSON: {"userId":123,"role":"user","exp":1234567890}. Decode with jq: echo 'eyJhbG...' | cut -d. -f2 | base64 -d | jq . (decodes payload). Token expiry: 'exp' field is Unix timestamp. If current time > exp, token expired, re-authenticate. Token formats: Bearer {token} (most common), Basic {base64(user:pass)} (less common). Token security: never log tokens, never hardcode in source code, transmit only over HTTPS. If token leaked, revoke by removing from server's whitelist (optional blacklist) or wait for expiry.

💡 Pro Tip: Extract token from response and save to variable: TOKEN=$(curl -s -X POST login_url -d creds | jq -r .token). Reuse: curl -H "Authorization: Bearer $TOKEN" api_url. This script-friendly pattern speeds up manual testing.

Open JWT Decoder

Read API documentation: endpoints, parameters, error codes

API docs explain: (1) Base URL (e.g., https://api.example.com/v1). (2) Endpoints: list all available paths (GET /users, POST /users, GET /users/{id}). (3) Parameters: path params (URL: /users/{id}), query params (URL: ?limit=10&offset=20), request body (JSON). (4) Response: example JSON, field descriptions, status codes. (5) Authentication: how to obtain and use tokens. (6) Rate limits: requests per minute. (7) Errors: status codes (401=unauthorized, 404=not found, 500=server error) and error messages. Example documentation entry: 'GET /users/{id}: Returns user by ID. Path param: id (integer). Response: {id, name, email, created_at}. Status: 200 (success), 404 (not found), 401 (unauthorized). Rate: 100 requests/minute.' Reading docs first prevents wasted debugging: you learn correct endpoint URLs, required parameters, expected response format. Without docs, you'd guess endpoints, get 404 errors, waste hours. Quality docs include code examples (cURL, Python, JavaScript), diagrams, and sandbox for testing.

💡 Pro Tip: Use API testing tools (Postman, Insomnia) to avoid memorizing cURL syntax. GUI lets you enter URL, headers, body visually. Save requests in collections for reuse. Share collections with team. These tools are 10x faster than cURL for complex requests.

Open Docs Reader

What You'll Have

Ability to make HTTP requests using cURL from command line with proper headers and parameters

Understanding of JSON structure and ability to parse/filter JSON responses using jq

Knowledge of JWT token lifecycle: obtain token from login, use in Authorization header, handle expiry

Familiarity with API documentation structure: endpoints, parameters, responses, error codes, rate limits

Tools in this workflow

cURL Tester

JSON Parser

JWT Decoder

Docs Reader

Follow this workflow in sequence to move from question to decision without losing context.

Why This Workflow Works

APIs are the backbone of modern software. Learning fundamentals (HTTP methods, status codes, request/response cycle) accelerates your ability to work with any API. cURL proficiency lets you debug quickly from terminal. JSON parsing skills prevent silent data bugs. JWT understanding unlocks authentication patterns used everywhere. Docs literacy prevents wasted time. Together, these four skills take you from API novice to confident user in 25 minutes.

FAQs

What's the difference between GET, POST, PUT, DELETE?

HTTP methods define action intent: GET (retrieve data, idempotent, no side effects), POST (create new resource, not idempotent), PUT (update/replace resource, idempotent), DELETE (remove resource, idempotent). GET /users returns all users. POST /users with body {name:'Alice'} creates new user. PUT /users/1 with body {name:'Alice Updated'} updates user 1. DELETE /users/1 removes user 1. Idempotent = calling multiple times = same result. Calling PUT same payload 3 times = same state. Calling POST 3 times = 3 new users (not idempotent). APIs should handle accidental retries gracefully: use idempotency keys (client provides unique key, server ignores duplicate requests with same key).

How do I know if my API request succeeded?

Status code indicates success/failure: 2xx (200 OK, 201 Created) = success. 4xx (400 bad request, 401 unauthorized, 404 not found) = client error. 5xx (500 server error, 503 service unavailable) = server error. Always check status code first. Then inspect response body: success responses include data; error responses include error message. Example: status 200 with body {"id":1,"name":"Alice"} = success. Status 401 with body {"error":"invalid token"} = auth failure. Status 404 = resource not found.

What's the difference between path parameters and query parameters?

Path params: part of URL path. Example: GET /users/{id} → /users/123 (id=123). Query params: after ? in URL. Example: GET /users?limit=10&offset=20 (limit=10, offset=20). Use path params for resource identity (which resource). Use query for filtering/pagination (how many, which subset). Example: GET /users/123/posts?limit=5 (path: user 123, query: get 5 most recent posts).

How do I handle API errors in my code?

Check status code, then parse error response: if status != 2xx, read error message from response body. Example: if status == 401, error message explains: 'token expired', 're-authenticate'. Log error with request details (URL, method, headers, body) for debugging. Implement retry logic for 5xx errors (server temporarily unavailable); don't retry 4xx (client error won't be fixed by retry). Implement exponential backoff: retry after 1s, 2s, 4s, 8s to avoid overwhelming overloaded server.

How often do API contracts change?

Depends on API maturity. Stable APIs (Google, Stripe, Twitter): rarely break (backward compatible). Young APIs (startup APIs, internal APIs): change often. Versioning: URL contains version /v1/ vs /v2/. Old version /v1/ supported for 1–2 years, then deprecated, then removed. When upgrading versions: test thoroughly (APIs change response fields, error codes, parameter names). Many outages caused by silent API contract changes. Monitor API provider's changelog. For your own API: version explicitly; communicate breaking changes; support old version for transition period.

More workflows

Security Critical4 steps

Secure REST API Setup

Implement JWT authentication, rate limiting, CORS policies, and UUID key generation for production APIs.

START WORKFLOW →

Beginner4 steps

Debug Failing API Request

Diagnose API errors: status codes, response inspection, headers, logs, and common pitfalls.

START WORKFLOW →

← Back to Workflows