You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
For organizations seeking expert guidance, strategic insights, or specialized support, our team of experienced professionals is here to help. Please reach out to our available core contributors for consultancy services.
- Include objects relationship (Comments/author) with the Article response:
111
-
- `/articles/:articleId?include=comments`
112
-
- `/articles/:articleId?include=comments,author`
113
-
- Create new Article:
114
-
- `/articles`
115
-
- Add new Comment to an Article:
116
-
- `/articles/:articleId/comments`
117
-
118
-
In the code above, we use the GET method on the path `/articles/:articleId/comments`.
119
-
We get `comments` on the article identified by `articleId` and then return it in the response.
120
-
We add `comments` after the `/articles/:articleId` path segment to indicate that it’s a child resource of /articles.
121
-
122
-
This makes sense since `comments` are the children objects of the `articles`,
123
-
assuming each article has its own comments.
124
-
Otherwise, it’s confusing to the user since this structure is generally accepted to be for accessing child objects.
125
-
The same principle also applies to the PUT, PATCH and DELETE endpoints.
126
-
They can all use the same kind of nesting structure for the path names.
127
-
128
-
## Handle Errors Gracefully And Return Standard Error Codes {#handle-errors-gracefully-and-return-standard-error-codes}
129
-
130
-
To eliminate confusion for API users when an error occurs,
131
-
we should handle errors gracefully and return HTTP response codes that indicate what kind of error occurred.
132
-
This gives maintainers of the API enough information to understand the problem that’s occurred.
133
-
We don’t want errors to bring down our system, so we can leave them unhandled,
134
-
which means that the API consumer has to handle them.
135
-
136
-
Common error HTTP status codes include:
137
-
- 200 OK Server successfully returned the requested data.
138
-
- 201 CREATED Server successfully created or modified the requested resource.
139
-
- 204 NO CONTENT Server successfully deleted the requested resource.
140
-
- 400 INVALID REQUEST The request was invalid or cannot be served. The exact error should be explained in the error payload. E.g. „The JSON is not valid“.
141
-
- 401 UNAUTHORIZED The request requires an user authentication.
142
-
- 403 FORBIDDEN The server understood the request, but is refusing it or the access is not allowed.
143
-
- 404 NOT FOUND There is no resource behind the URI.
144
-
- 422 Unprocessable Entity Should be used if the server cannot process the enitity, e.g. if an image cannot be formatted or mandatory fields are missing in the payload.
145
-
- 500 INTERNAL SERVER ERROR Internal Server Error.
146
-
- 502 BAD GATEWAY Server received an invalid response from the upstream server while trying to fulfill the request.
147
-
- 503 SERVICE UNAVAILABLE Service unavailable.
148
-
149
-
## Naming Conventions For [Routes](../components/main-components/routes.md) & [Actions](../components/main-components/actions.md) {#naming-conventions-for-routes-and-actions}
150
-
151
-
-**ListResources**: to fetch all resources.
152
-
-**FindResourceByID**: to search for a single resource by its unique identifier.
153
-
-**CreateResource**: to create a new resource.
154
-
-**UpdateResource**: to update/edit existing resource.
155
-
-**DeleteResource**: to delete a resource.
6
+
## REST API Best Practices
7
+
8
+
REST APIs are essential for enabling web interfaces and client-server communication. When designing REST APIs, it’s crucial to ensure security, performance, and ease of use for consumers. Following standardized practices and conventions reduces maintenance burdens and improves usability for developers consuming your API.
9
+
10
+
In this guide, we'll cover best practices for designing REST APIs that are intuitive, future-proof, secure, and performant.
11
+
12
+
---
13
+
14
+
### What Is a RESTful API? {#what-is-a-restful-api}
15
+
16
+
A RESTful API is an architectural style for web services based on stateless communication and cacheable data. REST APIs are typically accessed over HTTPS, and while they are not a formal protocol, they follow a set of conventions:
17
+
18
+
1.**Stateless Communication**: Each request from a client to a server must contain all information necessary to understand and process the request.
19
+
2.**Standard HTTP Methods**: REST APIs use HTTP methods such as GET, POST, PUT, PATCH, and DELETE.
20
+
3.**Cacheability**: Responses from REST APIs should be cacheable to improve performance.
21
+
22
+
---
23
+
24
+
### Use JSON for Requests and Responses {#accept-and-respond-with-json}
25
+
26
+
REST APIs should accept JSON in request payloads and respond with JSON-formatted data, which is universally supported across web technologies:
27
+
28
+
-**Compatibility**: JSON is widely supported across languages and frameworks.
29
+
-**Ease of Use**: JavaScript can natively encode and decode JSON, while server-side languages also support JSON processing.
30
+
31
+
---
32
+
33
+
### HTTP Methods for RESTful APIs {#http-methods-usage-in-restful-apis}
34
+
35
+
Using the correct HTTP method ensures that API operations are easy to understand and consistent:
Consistent naming helps maintainers and API consumers intuitively understand route purposes.
130
+
131
+
---
132
+
133
+
Following these best practices will ensure your REST API is robust, secure, and user-friendly for developers. Proper API design also reduces maintenance work and enhances compatibility with client applications.
0 commit comments