diff --git a/src/data/best-practices/api-security/content/api-gateway.md b/src/data/best-practices/api-security/content/api-gateway.md
index b71dbc20b..514003072 100644
--- a/src/data/best-practices/api-security/content/api-gateway.md
+++ b/src/data/best-practices/api-security/content/api-gateway.md
@@ -1 +1,15 @@
-# Api gateway
\ No newline at end of file
+# API Gateway
+
+> Use an API Gateway for caching, Rate Limit policies, and other security features.
+
+An API gateway can make your APIs more secure by providing a centralized point of control for managing and securing API traffic. Here are a few ways an API gateway can improve API security:
+
+- Authentication and authorization: API gateways can handle user authentication and authorization, reducing the burden on individual APIs and improving consistency across the organization. This can include techniques such as JWT verification, OAuth, and other authentication mechanisms.
+
+- Traffic filtering and rate limiting: An API gateway can enforce traffic filtering and rate limiting to protect APIs against DDoS attacks, brute force attacks, and other types of abuse.
+
+- Encryption and decryption: An API gateway can handle encryption and decryption of sensitive data to protect against data breaches and theft.
+
+- Logging and monitoring: An API gateway can provide centralized logging and monitoring of API traffic, helping to identify and respond to security threats and other issues.
+
+- Integration with security tools: An API gateway can be integrated with security tools such as WAFs, SIEMs, and other security tools to provide additional layers of protection.
\ No newline at end of file
diff --git a/src/data/best-practices/api-security/content/authorization-header.md b/src/data/best-practices/api-security/content/authorization-header.md
index c9f2b82e1..f88d07f13 100644
--- a/src/data/best-practices/api-security/content/authorization-header.md
+++ b/src/data/best-practices/api-security/content/authorization-header.md
@@ -1 +1,9 @@
-# Authorization header
\ No newline at end of file
+# Authorization Header
+
+> Use standard `Authorization` header for sending tokens instead of custom headers or query/body parameters
+
+Sending tokens in the query or body parameters is generally not recommended because these parameters may be logged or cached by various systems, including web servers, proxies, and gateways. This can potentially lead to the exposure of sensitive data, including authentication tokens.
+
+Additionally, sending tokens in query or body parameters can make them more vulnerable to cross-site request forgery (CSRF) attacks. In a CSRF attack, an attacker can trick a user into submitting a request that includes their authentication token, which the attacker can then use to impersonate the user and gain access to their account.
+
+By contrast, using the `Authorization` header to send tokens helps to ensure that the tokens are not logged or cached by intermediary systems, and it can also help to protect against CSRF attacks by allowing the server to validate the token before processing the request.
\ No newline at end of file
diff --git a/src/data/best-practices/api-security/content/avoid-http-blocking.md b/src/data/best-practices/api-security/content/avoid-http-blocking.md
index f8368fee7..d321d62b5 100644
--- a/src/data/best-practices/api-security/content/avoid-http-blocking.md
+++ b/src/data/best-practices/api-security/content/avoid-http-blocking.md
@@ -1 +1,5 @@
-# Avoid http blocking
\ No newline at end of file
+# Avoid HTTP Blocking
+
+> Avoid HTTP blocking if you are using huge amount of data by moving the HTTP heavy operations to background jobs or asynchronous tasks.
+
+HTTP blocking is a common issue in web applications. It occurs when the application is unable to process incoming HTTP requests due to a large number of requests or a large amount of data. This can lead to the application becoming unresponsive and the server crashing. This can be prevented by moving HTTP heavy operations to background jobs or asynchronous tasks. You can use a message queue to queue the requests and process them in the background. This will allow the application to continue processing other requests while the heavy operations are being processed in the background.
\ No newline at end of file
diff --git a/src/data/best-practices/api-security/content/avoid-personal-id-urls.md b/src/data/best-practices/api-security/content/avoid-personal-id-urls.md
index 56d21fb95..b488dedac 100644
--- a/src/data/best-practices/api-security/content/avoid-personal-id-urls.md
+++ b/src/data/best-practices/api-security/content/avoid-personal-id-urls.md
@@ -1 +1,5 @@
-# Avoid personal id urls
\ No newline at end of file
+# Avoid Personal ID in URLs
+
+> Avoid user’s personal ID in the resource URLs e.g. users/242/orders
+
+ User's own resource ID should be avoided. Use `/me/orders` instead of `/user/654321/orders`. This will help avoid the risk of exposing the user’s personal ID that can be used for further attacks.
\ No newline at end of file
diff --git a/src/data/best-practices/api-security/content/avoid-sensitive-data.md b/src/data/best-practices/api-security/content/avoid-sensitive-data.md
index 304dfe98e..979554e31 100644
--- a/src/data/best-practices/api-security/content/avoid-sensitive-data.md
+++ b/src/data/best-practices/api-security/content/avoid-sensitive-data.md
@@ -1 +1,5 @@
-# Avoid sensitive data
\ No newline at end of file
+# Avoid Returning Sensitive Data
+
+> Only return the data that is needed for the client to function.
+
+Returning only the data that is needed for the client to function is an important best practice for API security. This is because limiting the amount of data that is returned reduces the amount of sensitive information that is exposed. By only returning the necessary data, you can help prevent security vulnerabilities such as data leakage, injection attacks, and other types of attacks that rely on exposing too much information. Additionally, reducing the amount of data returned can improve the performance of your API by reducing the amount of data that needs to be processed and transmitted.
\ No newline at end of file
diff --git a/src/data/best-practices/api-security/content/cdn-for-file-uploads.md b/src/data/best-practices/api-security/content/cdn-for-file-uploads.md
index ab9b76d62..337b5da13 100644
--- a/src/data/best-practices/api-security/content/cdn-for-file-uploads.md
+++ b/src/data/best-practices/api-security/content/cdn-for-file-uploads.md
@@ -1 +1,5 @@
-# Cdn for file uploads
\ No newline at end of file
+# Use CDN for Uploads
+
+> Use CDN for file uploads
+
+Using a Content Delivery Network (CDN) for file uploads can make an API more secure by offloading the file upload traffic from the API server and reducing the risk of DDoS attacks.
\ No newline at end of file
diff --git a/src/data/best-practices/api-security/content/csp-header.md b/src/data/best-practices/api-security/content/csp-header.md
index 1162f17a0..9ff536c6c 100644
--- a/src/data/best-practices/api-security/content/csp-header.md
+++ b/src/data/best-practices/api-security/content/csp-header.md
@@ -1 +1,5 @@
-# Csp header
\ No newline at end of file
+# Content Security Policy
+
+> Send `Content-Security-Policy: default-src 'none'` header.
+
+Sending the `Content-Security-Policy: default-src 'none'` header is a security best practice that helps prevent cross-site scripting (XSS) attacks. This header tells the browser to not allow any resources to be loaded from external sources, such as scripts, stylesheets, or images. It only allows resources that are explicitly whitelisted in the CSP header, such as scripts or stylesheets hosted on your own domain. This can help prevent malicious actors from injecting code into your web pages via XSS attacks, as the browser will not execute any scripts or load any resources that are not explicitly allowed by the CSP policy.
\ No newline at end of file
diff --git a/src/data/best-practices/api-security/content/debug-mode-off.md b/src/data/best-practices/api-security/content/debug-mode-off.md
index 499f49c22..421e0100e 100644
--- a/src/data/best-practices/api-security/content/debug-mode-off.md
+++ b/src/data/best-practices/api-security/content/debug-mode-off.md
@@ -1 +1,5 @@
-# Debug mode off
\ No newline at end of file
+# Turn Debug Mode Off
+
+> Make sure to turn the debug mode off in production
+
+Debug mode is a feature that is used to help developers debug their code. It is not meant to be used in production. It can expose sensitive information about the application and the server it is running on. Make sure to turn debug mode off in production.
\ No newline at end of file
diff --git a/src/data/best-practices/api-security/content/disable-entity-expansion.md b/src/data/best-practices/api-security/content/disable-entity-expansion.md
index 4a236f969..25db7d24b 100644
--- a/src/data/best-practices/api-security/content/disable-entity-expansion.md
+++ b/src/data/best-practices/api-security/content/disable-entity-expansion.md
@@ -1 +1,5 @@
-# Disable entity expansion
\ No newline at end of file
+# Disable Entity Expansion
+
+> Disable entity expansion if using XML, YML or any other language
+
+Disabling entity expansion is important when using XML, YAML, or any other language that allows entities because it helps prevent XXE (XML External Entity) or YAML tag injection attacks. In these attacks, attacker normally injects some sort of custom code in the input to perform attacks against the application.. By disabling entity expansion, the input cannot be manipulated in this way, reducing the risk of such attacks.
\ No newline at end of file
diff --git a/src/data/best-practices/api-security/content/disable-entity-parsing-xml.md b/src/data/best-practices/api-security/content/disable-entity-parsing-xml.md
index 56fec7750..3b1ea9507 100644
--- a/src/data/best-practices/api-security/content/disable-entity-parsing-xml.md
+++ b/src/data/best-practices/api-security/content/disable-entity-parsing-xml.md
@@ -1 +1,7 @@
-# Disable entity parsing xml
\ No newline at end of file
+# Disable Entinty Parsing in XML
+
+> Disable entity parsing if you are parsing XML to avoid XXE attacks
+
+If the XML parser is vulnerable to XXE attacks, the attacker can use this vulnerability to read files on the server, perform SSRF attacks, and more. This can lead to the disclosure of sensitive information, denial of service, and other attacks.
+
+XXE (XML External Entity) attack is a type of attack that targets applications that parse XML input from untrusted sources. In this attack, an attacker injects a malicious XML payload. This payload can contain external entities that the attacker can use to retrieve sensitive data, execute remote code, or launch denial of service attacks. XXE attacks can be prevented by disabling external entity processing or by validating and sanitizing the XML input before parsing it.
\ No newline at end of file
diff --git a/src/data/best-practices/api-security/content/endpoint-authentication.md b/src/data/best-practices/api-security/content/endpoint-authentication.md
index 45f5349c8..4a0c53460 100644
--- a/src/data/best-practices/api-security/content/endpoint-authentication.md
+++ b/src/data/best-practices/api-security/content/endpoint-authentication.md
@@ -1 +1,6 @@
-# Endpoint authentication
\ No newline at end of file
+# Endpoint Authentication
+
+> Check if all the protected endpoints are behind authentication
+to avoid broken authentication process
+
+By identifying and fixing broken authentication workflows, the API can prevent attacks such as brute force attacks, credential stuffing, session hijacking, and other authentication-related attacks. This can help ensure that the system is secure and that sensitive data is protected.
\ No newline at end of file
diff --git a/src/data/best-practices/api-security/content/force-content-type.md b/src/data/best-practices/api-security/content/force-content-type.md
index ec4612261..60949eb1d 100644
--- a/src/data/best-practices/api-security/content/force-content-type.md
+++ b/src/data/best-practices/api-security/content/force-content-type.md
@@ -1 +1,5 @@
-# Force content type
\ No newline at end of file
+# Force Content-Type
+
+> Always force the `Content-Type` header to be set to relevant MIME type.
+
+Forcing the content-type for API security is important because it ensures that the client and server are communicating in a mutually agreed-upon format for the data being transmitted. This can prevent attacks such as content spoofing or injection, where an attacker tries to trick the server into processing malicious content by pretending that it is of a different content type. By forcing the content-type to a specific format, the server can validate that the data it is receiving is legitimate and safe to process. Additionally, forcing the content-type can help prevent certain types of parsing errors that could be exploited by attackers.
\ No newline at end of file
diff --git a/src/data/best-practices/api-security/content/no-sniff-header.md b/src/data/best-practices/api-security/content/no-sniff-header.md
index 4ee6b8496..1fbe4c5b6 100644
--- a/src/data/best-practices/api-security/content/no-sniff-header.md
+++ b/src/data/best-practices/api-security/content/no-sniff-header.md
@@ -1 +1,7 @@
-# No sniff header
\ No newline at end of file
+# X-Content-Type-Options: nosniff
+
+> Send `X-Content-Type-Options: nosniff` header.
+
+You should send the `X-Content-Type-Options: nosniff` header to prevent [MIME type sniffing attacks](https://www.keycdn.com/support/what-is-mime-sniffing) on your web application. This header tells the browser not to override the response content type even if it's not the expected type. For example, if an attacker manages to upload an HTML file with a disguised extension like .jpg, the server may still send the correct content type header for the HTML file. However, some browsers may ignore this header and try to "sniff" the content type based on the actual contents of the file, leading to a potential cross-site scripting (XSS) attack.
+
+By sending the `X-Content-Type-Options: nosniff` header, you tell the browser to always trust the provided content type and not try to sniff the content type. This helps to mitigate the risk of attackers exploiting content type mismatches to deliver malicious content to unsuspecting users.
\ No newline at end of file
diff --git a/src/data/best-practices/api-security/content/non-executable-stacks.md b/src/data/best-practices/api-security/content/non-executable-stacks.md
index f0f76409a..33088fcfa 100644
--- a/src/data/best-practices/api-security/content/non-executable-stacks.md
+++ b/src/data/best-practices/api-security/content/non-executable-stacks.md
@@ -1 +1,7 @@
-# Non executable stacks
\ No newline at end of file
+# Non-Executable Stacks
+
+> Use non-executable stacks to prevent attackers from executing code on your server.
+
+A stack usually refers to the call stack or execution stack. It is a data structure used by the computer program to manage and keep track of the sequence of function calls, local variables, and other related data during the execution of the program.
+
+A non-executable stack is a security mechanism that prevents malicious code from being executed by preventing the stack memory from being executed as code. This helps to prevent attacks such as buffer overflow attacks, where an attacker tries to overwrite the return address on the stack to redirect the program to execute malicious code. By using non-executable stacks, the program can keep the stack separate from executable code and help prevent these types of attacks.
\ No newline at end of file
diff --git a/src/data/best-practices/api-security/content/oauth-state.md b/src/data/best-practices/api-security/content/oauth-state.md
index 68b3495b2..0b21fbd65 100644
--- a/src/data/best-practices/api-security/content/oauth-state.md
+++ b/src/data/best-practices/api-security/content/oauth-state.md
@@ -1 +1,9 @@
-# Oauth state
\ No newline at end of file
+# Use State Param
+
+> Use state parameter to avoid CSRF attacks
+
+In OAuth, the `state` parameter is used as a security measure to prevent CSRF (Cross-Site Request Forgery) attacks. CSRF attacks occur when a malicious website or script sends a request to a legitimate website on behalf of a user who is currently authenticated.
+
+To prevent CSRF attacks, the `state` parameter is used to store a unique value that is generated by the client application before initiating the authorization request. This value is included in the authorization request and then verified by the authorization server when the user is redirected back to the client application. If the `state` value in the authorization response matches the `state` value that was sent by the client application, the authorization is considered valid and the access token is returned to the client.
+
+By using the `state` parameter, you can help to prevent malicious actors from intercepting or modifying the authorization request in transit, as the unique `state` value is only known to the client application and the authorization server. This can help to ensure the integrity and security of the OAuth flow and protect against CSRF attacks.
diff --git a/src/data/best-practices/api-security/content/oauth-validate-scope.md b/src/data/best-practices/api-security/content/oauth-validate-scope.md
index 63f7bba1a..0211ae5ee 100644
--- a/src/data/best-practices/api-security/content/oauth-validate-scope.md
+++ b/src/data/best-practices/api-security/content/oauth-validate-scope.md
@@ -1 +1,13 @@
-# Oauth validate scope
\ No newline at end of file
+# Validate Scope
+
+> Have default scope, and validate scope for each application
+
+In OAuth, scopes are used to specify the permissions and access levels that are granted to client applications when accessing protected resources on behalf of a user.
+
+The best practice of having a default scope and validating the scope for each application is important because it helps to ensure that client applications only have access to the resources that they require, and that users are only granting the necessary permissions to each application.
+
+The default scope is a set of permissions that are granted to all client applications by default, unless otherwise specified by the user. By having a default scope, you can ensure that all applications are subject to the same baseline security and access controls.
+
+In addition to having a default scope, it is also recommended to validate the scope for each application. This means that when a user grants access to an application, the server should check to ensure that the requested scope is valid and appropriate for that application. This can help to prevent malicious applications from requesting excessive permissions or unauthorized access to user data.
+
+By having a default scope and validating the scope for each application, you can help to ensure that the OAuth flow is secure and that client applications are only accessing the resources and permissions that they require.
diff --git a/src/data/best-practices/api-security/content/only-server-side-encryption.md b/src/data/best-practices/api-security/content/only-server-side-encryption.md
index 48b44c6ae..d17b63091 100644
--- a/src/data/best-practices/api-security/content/only-server-side-encryption.md
+++ b/src/data/best-practices/api-security/content/only-server-side-encryption.md
@@ -1 +1,5 @@
-# Only server side encryption
\ No newline at end of file
+# Avoid Client-Side Encryption
+
+> Use server-side encryption instead of client-side encryption
+
+Client-side encryption is not recommended because client side codebase can be easily reverse engineered which can lead to the exposure of encryption algorithms.
\ No newline at end of file
diff --git a/src/data/best-practices/api-security/content/prefer-uuid.md b/src/data/best-practices/api-security/content/prefer-uuid.md
index 8403d86a9..6f1ed4da4 100644
--- a/src/data/best-practices/api-security/content/prefer-uuid.md
+++ b/src/data/best-practices/api-security/content/prefer-uuid.md
@@ -1 +1,5 @@
-# Prefer uuid
\ No newline at end of file
+# Prefer UUIDs
+
+> Use UUIDs instead of auto-incrementing integers. UUIDs are globally unique, and are not sequential. They are also more difficult to guess than sequential integers.
+
+Use of UUIDs over auto-incrementing IDs prevents attackers from guessing or iterating through resource IDs. UUIDs are randomly generated and contain 128 bits of entropy, making it practically impossible for attackers to guess them. In contrast, autoincrementing IDs can be easily predicted or iterated through, allowing attackers to access or manipulate resources they shouldn't have access to. Additionally, using UUIDs can help prevent information disclosure by hiding the order of resource creation or access.
\ No newline at end of file
diff --git a/src/data/best-practices/api-security/content/proper-http-methods.md b/src/data/best-practices/api-security/content/proper-http-methods.md
index 8cdec00b4..e0f99f351 100644
--- a/src/data/best-practices/api-security/content/proper-http-methods.md
+++ b/src/data/best-practices/api-security/content/proper-http-methods.md
@@ -1 +1,5 @@
-# Proper http methods
\ No newline at end of file
+# Proper HTTP Methods
+
+Use the proper HTTP method according to the operation: `GET (read)`, `POST (create)`, `PUT/PATCH (replace/update)`, and `DELETE (to delete a record)`, and respond with `405 Method Not Allowed` if the requested method isn't appropriate for the requested resource.
+
+
diff --git a/src/data/best-practices/api-security/content/proper-response-code.md b/src/data/best-practices/api-security/content/proper-response-code.md
index 99456a265..fa1ee405c 100644
--- a/src/data/best-practices/api-security/content/proper-response-code.md
+++ b/src/data/best-practices/api-security/content/proper-response-code.md
@@ -1 +1,10 @@
-# Proper response code
\ No newline at end of file
+# Proper Response Code
+
+> Return the proper status code according to the operation completed. e.g.
+> - `200 OK`
+> - `400 Bad Request`
+> - `401 Unauthorized`
+> - `405 Method Not Allowed`
+> - ...etc.
+
+Returning the proper status code according to the operation completed is important for API security because it allows the client to understand the outcome of their request and take appropriate actions. For example, if the server returns a 401 Unauthorized status code, the client knows that their authentication credentials are incorrect and can prompt the user to re-enter their login details. On the other hand, if the server returns a 200 OK status code even though the request failed, the client may not realize there was an issue and could potentially execute malicious actions or display incorrect data. Providing accurate status codes can help prevent security vulnerabilities and improve the overall reliability and usability of the API.
\ No newline at end of file
diff --git a/src/data/best-practices/api-security/content/remove-fingerprint-header.md b/src/data/best-practices/api-security/content/remove-fingerprint-header.md
index 6e1b1c214..7ee9f6801 100644
--- a/src/data/best-practices/api-security/content/remove-fingerprint-header.md
+++ b/src/data/best-practices/api-security/content/remove-fingerprint-header.md
@@ -1 +1,5 @@
-# Remove fingerprint header
\ No newline at end of file
+# Remove Fingerprints
+
+> Remove fingerprinting headers (i.e. x-powered-by etc) from the HTTP request.
+
+Fingerprinting headers can be used to identify the web server and its version. This information can be used by attackers to identify vulnerabilities in the web server and exploit them.
\ No newline at end of file
diff --git a/src/data/best-practices/api-security/content/response-type-token.md b/src/data/best-practices/api-security/content/response-type-token.md
index 46e37db1e..423818b13 100644
--- a/src/data/best-practices/api-security/content/response-type-token.md
+++ b/src/data/best-practices/api-security/content/response-type-token.md
@@ -1 +1,11 @@
-# Response type token
\ No newline at end of file
+# Avoid Implicit Grant Flow
+
+> Avoid `response_type=token’ and try to exchange for code instead.
+
+In OAuth, `response_type=token` is a method for obtaining an access token directly from the authorization endpoint, without using an authorization code. This method is known as the implicit grant flow.
+
+However, it is recommended to avoid using `response_type=token` and instead use the authorization code grant flow, where the client exchanges an authorization code for an access token. This is because the implicit grant flow can be less secure than the authorization code grant flow.
+
+The reason for this is that the access token is returned directly to the client in the URL fragment of the redirect URI. This means that the access token could be intercepted or exposed in the browser history or server logs. In contrast, with the authorization code grant flow, the access token is returned to the client only after the client has exchanged the authorization code for the token using a secure server-to-server communication.
+
+Therefore, by using the authorization code grant flow instead of the implicit grant flow, you can help to protect the access token from being exposed or intercepted by malicious actors.
diff --git a/src/data/best-practices/api-security/content/validate-content-type.md b/src/data/best-practices/api-security/content/validate-content-type.md
index 3d9e71764..54d744863 100644
--- a/src/data/best-practices/api-security/content/validate-content-type.md
+++ b/src/data/best-practices/api-security/content/validate-content-type.md
@@ -1 +1,6 @@
-# Validate content type
\ No newline at end of file
+# Content Type Validation
+
+> Validate `content-type` on request headers to prevent XSS attacks
+
+Validating the `Content-Type` header on the request can help to make APIs more secure by ensuring that the request data is in the expected format and reducing the risk of attacks such as injection attacks or cross-site scripting (XSS).
+
diff --git a/src/data/best-practices/api-security/content/validate-user-input.md b/src/data/best-practices/api-security/content/validate-user-input.md
index ef8b5053f..b3df39ab8 100644
--- a/src/data/best-practices/api-security/content/validate-user-input.md
+++ b/src/data/best-practices/api-security/content/validate-user-input.md
@@ -1 +1,5 @@
-# Validate user input
\ No newline at end of file
+# Validate User Input
+
+> Validate user input to avoid common vulnerabilities
+
+User input is a common source of vulnerabilities in web applications. This is because user input is often not properly validated, sanitized, or escaped before being used in a web application. This can allow an attacker to manipulate the input and execute malicious code or cause the application to behave unexpectedly.
\ No newline at end of file
diff --git a/src/data/best-practices/api-security/content/x-frame-options-deny.md b/src/data/best-practices/api-security/content/x-frame-options-deny.md
index 0992b016e..2d24d7144 100644
--- a/src/data/best-practices/api-security/content/x-frame-options-deny.md
+++ b/src/data/best-practices/api-security/content/x-frame-options-deny.md
@@ -1 +1,5 @@
-# X frame options deny
\ No newline at end of file
+# X-Frame-Options: Deny
+
+> Send `X-Frame-Options: deny` header.
+
+The `X-Frame-Options` header prevents the page from being displayed in an iframe, which is commonly used in clickjacking attacks. By setting the value of this header to `deny`, you are telling the browser not to display the page in any iframe. This helps prevent the page from being embedded within an attacker's website and reduces the risk of clickjacking attacks.
\ No newline at end of file