{"id":18961707,"url":"https://github.com/pt-dot/restful-api-standardization","last_synced_at":"2026-01-27T23:44:21.887Z","repository":{"id":68608048,"uuid":"212077840","full_name":"pt-dot/restful-api-standardization","owner":"pt-dot","description":"DOT Indonesia RESTful API standardization for design, request \u0026 response format, and best practices","archived":false,"fork":false,"pushed_at":"2020-01-23T07:07:44.000Z","size":13,"stargazers_count":7,"open_issues_count":5,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-01-01T04:52:46.051Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/pt-dot.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,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-10-01T11:21:59.000Z","updated_at":"2024-09-23T15:20:07.000Z","dependencies_parsed_at":"2023-07-03T04:31:15.616Z","dependency_job_id":null,"html_url":"https://github.com/pt-dot/restful-api-standardization","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pt-dot%2Frestful-api-standardization","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pt-dot%2Frestful-api-standardization/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pt-dot%2Frestful-api-standardization/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pt-dot%2Frestful-api-standardization/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pt-dot","download_url":"https://codeload.github.com/pt-dot/restful-api-standardization/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239958313,"owners_count":19724926,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":[],"created_at":"2024-11-08T14:14:04.061Z","updated_at":"2026-01-27T23:44:21.857Z","avatar_url":"https://github.com/pt-dot.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# RESTful API Guideline\n\n## Overview\nDOT Indonesia has a guideline as well as standardization in making RESTful API. This is about how to design and develop RESTful API for internal developers or vendor partners in order that to ensure that APIs are developed according to standards.\n\n## URL Design\nWhen determining an API’s URL structure, it is helpful to consider that all of its resources exist in a single “reference document” in which each resource is addressable at a unique path. Resources are grouped by type at the top level of this document. Individual resources are keyed by ID within these typed collections. Attributes and links within individual resources are uniquely addressable according to the resource object structure described above.\n\nThe URL should contain resources (nouns), not actions or verbs. And the resource should always be plural in the API endpoint and if we want to access one instance of the resource, we can always pass the id in the URL.\n\nHere are the examples:\n- `/photos`\n- `/products`\n- `/categories`\n- etc.\n\nThe following examples are about breaking down a resource according to the HTTP verbs:\n- GET `/photos`, should get the list of all photos\n- GET `/photos/1`, should get the detail of photos with ID `1`\n- POST `/photos`, should store single photo resource\n- PUT `/photos/1`, should update detail of photos with ID `1`\n- DELETE `/photos/1`, should delete photo with ID `1`\n\n### Related Resource URL\nIt is recommended that a related resource URL be formed by appending the name of the relationship to the resource’s URL.\n\nFor example, the URL for product's `variants` would be:\n```\n/products/1/variants\n```\n\nAnd the URL for a product's `images` would be:\n```\n/products/1/images\n```\n\n## Request Format\n## Response Format\nThis section describe the structure of a JSON:API document for response format. A JSON object **MUST** be at the root of every JSON:API response containing data. This object defines a document’s “top level\".\n\nA document **MUST** contain at least one of the following top-level members:\n- `data` : the document's \"primary data\"\n- `errors` : an array of error objects\n\n### Successful Response\n\nIn a successful response, there is a primary data that's a representation of the resource or collection of resources targeted by request.\n\nPrimary data **MUST** be either:\n- a single resource object or `null`, for requests that target single resource\n- an array of resource objects or an empty array (`[]`), for requests that target resource collections\n\nFor example, the following primary data is a single resource object:\n```\n{\n    \"success\": true,\n    \"message\": \"This is successful message\",\n    \"data\": {\n        \"id\": 1,\n        \"type\": \"articles\",\n        \"created_at\": \"2019-10-04 14:33\"\n    }\n}\n```\n\nThe following primary data is an array of resource objects:\n```\n{\n    \"success\": true,\n    \"message\": \"This is successful message\",\n    \"data\": [\n        {\n            \"id\": 1,\n            \"type\": \"articles\",\n            \"created_at\": \"2019-10-04 13:33\"\n        },\n        {\n            \"id\": 2,\n            \"type\": \"articles\",\n            \"created_at\": \"2019-10-04 14:33\"\n        }\n    ]\n}\n```\n\n### Failed Response\nA server **MAY** choose to stop processing as soon as a problem is encountered, or it **MAY** continue processing and encounter multiple problems. For instance, a server might process multiple attributes and then return multiple validation problems in a single response.\n\n#### Error Objects\nError objects provide additional information about problems encountered while performing an operation. Error objects **MUST** be returned as an array keyed by errors in the top level of a JSON:API document.\n\nThe following example is format usually used for failed response with status code 400, 401, 404, or 500:\n```\n{\n    \"success\": false,\n    \"error-code\": null, /* or optional error payload, eg: 3001, 3002, etc. */\n    \"errors\": [],\n    \"message\": \"Error xyz has occurred\"\n}\n```\n\nFor returning multiple validation problems, it **MUST** return error messages inside an array. Inside the `errors` array **MUST** contain the following element:\n- `key` : taken from request body's property that doesn't pass the validation\n- `value`: is the validation error message\n\nHere's the example for multiple validation problems only contains value of error:\n```\n{\n    \"success\": false,\n    \"error-code\": null, /* or optional error payload, eg: 3001, 3002, etc. */\n    \"errors\": [\n        \"The email must be a valid email\",\n        \"The password must be at least 6 chaarcters\",\n        \"The phone number is already used\"\n    ],\n    \"message\": \"Error xyz has occurred\"\n}\n```\n\nHere's the example for multiple validation problems contains field and value of error:\n```\n{\n    \"success\": false,\n    \"error-code\": null, /* or optional error payload, eg: 3001, 3002, etc. */\n    \"errors\": {\n        \"email\": \"The email must be a valid email\",\n        \"password\": \"The password must be at least 6 chaarcters\",\n        \"phone\": \"The phone number is already used\"\n    },\n    \"message\": \"Error xyz has occurred\"\n}\n```\n\n## HTTP Response Code\nHTTP response status code indicate whether a specific HTTP request hasbeen successfully completed. There are 3 types of response code usually used:\n- Successful response (`2xx`)\n- Client errors (`4xx`)\n- Server errors (`5xx`)\n\n### Successful Responses (`2xx`)\n**200 OK**\n\nThe request has succeeded. The meaning of the success depends on the HTTP method:\n- `GET`: The resource has been fetched and is transmitted in the message body.\n- `PUT or POST`: The resource describing the result of the action is transmitted in the message body.\n\n**201 Created**\n\nThe request has succeeded and a new resource has been created as a result. This is typically the response sent after `POST` requests, or some `PUT` requests.\n\n### Client Error Responses (`4xx`)\n**400 Bad Request**\n\nThe server could not understand the request due to invalid syntax.\n\n**401 Unauthorized**\n\nAlthough the HTTP standard specifies \"unauthorized\", semantically this response means \"unauthenticated\". That is, the client must authenticate itself to get the requested response.\n\n**404 Not Found**\n\nThe server couldn't find requested resource. This can be the URL / endpoint or the data that client looking for is not exists.\n\n**405 Method Not Allowed**\n\nThe request method is known by the server, but has been disabled and cannot be used. For example:\n\u003e An endpoint `/users/1` must be requested using `GET` HTTP verb, but we access it using `POST` HTTP verb.\n\nAccording to the case above, the server will return a response with the `405` status code.\n\n### Server Error Response (`5xx`)\n**500 Internal Server Error**\n\nThis means that the server has encountered a situation it doesn't know how to handle. For example when a failure occurred in deleting data.\n\n**502 Bad Gateway**\n\nThis error response means that the server, while working as a gateway to get a response needed to handle the request, got an invalid response. Or in short, when our server is down.\n\n## Error Code\n## Panduan Kontribusi\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpt-dot%2Frestful-api-standardization","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpt-dot%2Frestful-api-standardization","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpt-dot%2Frestful-api-standardization/lists"}