{"id":16251735,"url":"https://github.com/nilandev/restful-api-guidelines","last_synced_at":"2026-02-05T21:32:02.375Z","repository":{"id":83167486,"uuid":"96876106","full_name":"nilandev/restful-api-guidelines","owner":"nilandev","description":"Checklist of the most important security countermeasures when designing, testing, and releasing your API.","archived":false,"fork":false,"pushed_at":"2023-10-07T00:33:33.000Z","size":10,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-07-26T19:42:11.340Z","etag":null,"topics":["api","api-testing","rest-api","security-testing"],"latest_commit_sha":null,"homepage":"http://stacktips.com","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nilandev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2017-07-11T09:30:27.000Z","updated_at":"2023-10-13T18:39:28.000Z","dependencies_parsed_at":"2023-10-05T04:02:23.401Z","dependency_job_id":"c5545825-c1d0-4122-96eb-ac992f63b7fe","html_url":"https://github.com/nilandev/restful-api-guidelines","commit_stats":null,"previous_names":["nilandev/api-security-guidelines","nilandev/restful-api-guidelines"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/nilandev/restful-api-guidelines","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nilandev%2Frestful-api-guidelines","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nilandev%2Frestful-api-guidelines/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nilandev%2Frestful-api-guidelines/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nilandev%2Frestful-api-guidelines/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nilandev","download_url":"https://codeload.github.com/nilandev/restful-api-guidelines/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nilandev%2Frestful-api-guidelines/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29135047,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-05T20:50:26.975Z","status":"ssl_error","status_checked_at":"2026-02-05T20:49:26.082Z","response_time":65,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","api-testing","rest-api","security-testing"],"created_at":"2024-10-10T15:11:11.690Z","updated_at":"2026-02-05T21:32:02.354Z","avatar_url":"https://github.com/nilandev.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# RESTful API Design Best Practices\n\nREST (Representational State Transfer) is a software architectural style that has become the de-facto standard for building API-driven applications. Some of the key characteristics of RESTful API's include:\n\n* Client-server architecture: REST APIs are typically designed using a client-server architecture, where the client is responsible for making requests to the server and the server is responsible for responding to those requests.\n* Statelessness: REST APIs are stateless, meaning that each request is independent of any other request. This makes REST APIs easier to scale and more resilient to failures.\n* Cacheability: REST APIs typically return cacheable responses, which means that the client can store the responses and reuse them for subsequent requests. This can improve performance and reduce bandwidth usage.\n* Layered system: REST APIs are typically designed as a layered system, where each layer is responsible for a specific task. This makes REST APIs easier to develop and maintain.\n* Uniform interface: REST APIs use a uniform interface, which means that they use a consistent set of HTTP methods and URIs to perform different operations. This makes REST APIs easier to learn and use.\n\n## 🥇 API Design Best Practices\n* Use HTTP Methods Properly.\n* Use Proper HTTP Status Codes\n* Consistent design and using appropriate resource schema\n* Implement HATEOAS\n* API Versioning\n* Pagination, Filtering and Searching\n* Standard Error handling practices\n* Documentation\n\n## :key: API Security Guidelines\nChecklist of the most important security countermeasures when designing, testing, and releasing your API.\n\n## Authentication\n- Don't use `Basic Auth` Use standard authentication (e.g. JWT, OAuth).\n- Don't reinvent the wheel in `Authentication`, `token generating`, `password storing` use the standards.\n- Use OAuth 2.0. It is the industry-standard protocol for authorization works for web, desktop, or mobile applications. Read more about OAuth 2.0 [here](https://oauth.net/2/).\n\n### JWT (JSON Web Token)\n- Use a random complicated key (`JWT Secret`) to make brute forcing tokens very hard.\n- Don't extract the algorithm from the payload. Force algorithm in the backend (`HS256` or `RS256`). \n- Make token expiration (`TTL`, `RTTL`) as short as possible.\n- Don't store sensitive data in the JWT payload, it can be decoded [easily](https://jwt.io/#debugger-io).\n\n### OAuth\n- Always validate `redirect_uri` on the server side to allow only whitelisted URLs.\n- Always try to exchange for code not tokens (don't allow `response_type=token`).\n- Use `state` parameter with a random hash to prevent CSRF on the OAuth authentication process.\n- Define default scope, and validate scope parameters for each application. \n\n## Access\n- Limit requests (Throttling) to avoid DDoS / Bruteforce attacks.\n- Use HTTPS on the server side to avoid MITM (Man In The Middle Attack).\n- Use `HSTS` header with SSL to avoid SSL Strip attack.\n\n## Input\n- Use proper HTTP method according to operation, `GET (read)`, `POST (create)`, `PUT (replace/update)` and `DELETE (to delete a record)`.\n- Validate `content-type` on request Accept header ( Content Negotiation ) to allow only your supported format (e.g. `application/xml` , `application/json` ... etc) and respond with `406 Not Acceptable` response if not matched.\n- Validate `content-type` of posted data as you accept (e.g. `application/x-www-form-urlencoded` , `multipart/form-data ,application/json` ... etc ).\n- Validate User input to avoid common vulnerabilities (e.g. `XSS`, `SQL-Injection` , `Remote Code Execution` ... etc).\n- Don't use any sensitive data ( `credentials` , `Passwords`, `security tokens`, or `API keys`) in the URL, but use standard Authorization header.\n\n## Processing\n- Check if all endpoints are protected behind the authentication to avoid broken authentication.\n- User's own resource ID should be avoided. Use `/me/orders` instead of `/user/654321/orders`\n- Don't use auto-increment ID use `UUID` instead.\n- If you are parsing XML files, make sure entity parsing is not enabled to avoid `XXE` (XML external entity attack).\n- If you are parsing XML files, make sure entity expansion is not enabled to avoid `Billion Laughs/XML bomb` via exponential entity expansion attack.\n- Use CDN for file uploads.\n- If you are dealing with a huge amount of data, use Workers and Queues to return responses fast to avoid HTTP Blocking. \n- Do not forget to turn the DEBUG mode OFF.\n\n## Output\n- Send `X-Content-Type-Options: nosniff` header.\n- Send `X-Frame-Options: deny` header.\n- Send `Content-Security-Policy: default-src 'none'` header.\n- Remove fingerprinting headers - `X-Powered-By`, `Server`, `X-AspNet-Version` etc.\n- Force `content-type` for your response, if you return `application/json` then your response `content-type` is `application/json`.\n- Don't return sensitive data like `credentials`, `Passwords`, or `security tokens`.\n- Return the proper status code according to the operation completed. (e.g. `200 OK` , `400 Bad Request` , `401 Unauthorized`, `405 Method Not Allowed` ... etc).\n\n## Contribution\nFeel free to contribute, :octocat:\tfork -\u003e edit -\u003e submit pull request.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnilandev%2Frestful-api-guidelines","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnilandev%2Frestful-api-guidelines","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnilandev%2Frestful-api-guidelines/lists"}