api-standards

This is Freighthub API guidelines, forked from PayPal

You can find the actual guidelines here

You can find examples and patterns here

You can find the list of references here

You can find the JSON schema spec here

TL;DR

Paths: kebab case and plurals ✅ purchase-orders 🚫purchaseOrder, purchaseOrders, purchase_orders

Query Params: camelCase ✅ customerID 🚫customer-id, customer_id, customerId

Path Params: camelCase ✅ customerID 🚫customer-id, customerId

Headers: Pascal-Case, no X- for custom headers ✅ API-Key 🚫api-key, apiKey, X-API-Key

Responses: must be an object with camelCase properties ✅ customerID, id 🚫customer-id,customerId, _id

Pagination: must take page and pageSize parameters and response must contains a property items and should contain totalItems for the respones (also accepted is totalPages)

Sorting: should take a sort parameter following the pattern {field_name}|{asc|desc} where {field_name} is a property of the resource ✅ createdAt|asc,activatedAt|desc

Enums: must be camcelCase ✅ green, blue, blueGreen 🚫 BLUE, blue_green

Acronyms: must be all lower or all upper case ✅ HTTP, API, HTTPHeader, { "httpHeader": "" }, { "id": 1 } 🚫 Http, Api