Skip to content

Commit

Permalink
Merge pull request #861 from adib-yg/master
Browse files Browse the repository at this point in the history 
Improve HTTP documentation
  • Loading branch information
@adib-yg
adib-yg authored Jan 26, 2024
2 parents 563fd59 + 2b1fb01 commit 7e67375
Show file tree
Hide file tree
Showing 4 changed files with 116 additions and 31 deletions.
63 changes: 32 additions & 31 deletions docs/scripting/functions/HTTP.md
View file
Original file line number Diff line number Diff line change
@@ -1,22 +1,20 @@
---
title: HTTP
description: Sends a threaded HTTP request.
tags: []
tags: ["http"]
---

<VersionWarn version='SA-MP 0.3b' />

## Description

Sends a threaded HTTP request.

| Name | Description |
| ---------- | ------------------------------------------------------------------------------------------- |
| index | ID used to differentiate requests that are sent to the same callback (useful for playerids) |
| type | The type of request you wish to send. |
| url[] | The URL you want to request. (Without 'http://') |
| data[] | Any POST data you want to send with the request. |
| callback[] | Name of the callback function you want to use to handle responses to this request. |
| Name | Description |
|--------------------|---------------------------------------------------------------------------------------------|
| index | ID used to differentiate requests that are sent to the same callback (useful for playerids) |
| HTTP_METHOD:method | The [type](../resources/http-request-methods) of request you wish to send. |
| const url[] | The URL you want to request. **(Without 'http://')** |
| const data[] | Any POST data you want to send with the request. |
| const callback[] | Name of the callback function you want to use to handle responses to this request. |

## Returns

Expand All @@ -25,19 +23,19 @@ Sends a threaded HTTP request.
## Definitions

```c
// HTTP requests
#define HTTP_GET (1) // Sends a regular HTTP request.
#define HTTP_POST (2) // Sends a HTTP request with POST data.
#define HTTP_HEAD (3) // Sends a regular HTTP request, but ignores any response data - returning only the response code.
// HTTP request types
#define HTTP_GET (HTTP_METHOD:1) // Sends a regular HTTP request.
#define HTTP_POST (HTTP_METHOD:2) // Sends a HTTP request with POST data.
#define HTTP_HEAD (HTTP_METHOD:3) // Sends a regular HTTP request, but ignores any response data - returning only the response code.

// HTTP error response codes
// These codes compliment ordinary HTTP response codes returned in 'response_code'
// (10x) (20x OK) (30x Moved) (40x Unauthorised) (50x Server Error)
#define HTTP_ERROR_BAD_HOST (1)
#define HTTP_ERROR_NO_SOCKET (2)
#define HTTP_ERROR_CANT_CONNECT (3)
#define HTTP_ERROR_CANT_WRITE (4)
#define HTTP_ERROR_CONTENT_TOO_BIG (5)
#define HTTP_ERROR_MALFORMED_RESPONSE (6)
#define HTTP_ERROR_BAD_HOST (HTTP_ERROR:1)
#define HTTP_ERROR_NO_SOCKET (HTTP_ERROR:2)
#define HTTP_ERROR_CANT_CONNECT (HTTP_ERROR:3)
#define HTTP_ERROR_CANT_WRITE (HTTP_ERROR:4)
#define HTTP_ERROR_CONTENT_TOO_BIG (HTTP_ERROR:5)
#define HTTP_ERROR_MALFORMED_RESPONSE (HTTP_ERROR:6)
```

## Examples
Expand All @@ -47,30 +45,30 @@ forward MyHttpResponse(index, response_code, data[]);

public OnPlayerCommandText(playerid, cmdtext[])
{
if (!strcmp("/hello",cmdtext,true))
if (!strcmp("/hello", cmdtext, true))
{
HTTP(playerid, HTTP_GET, "kc.gd/hello.txt", "", "MyHttpResponse");
HTTP(playerid, HTTP_GET, "open.mp/hello.txt", "", "MyHttpResponse");
return 1;
}
return 0;
}

public MyHttpResponse(index, response_code, data[])
{
// In this callback "index" would normally be called "playerid" ( if you didn't get it already:) )
new
buffer[ 128 ];
if (response_code == 200) //Did the request succeed?
// In this callback "index" would normally be called "playerid" ( if you didn't get it already )
new buffer[128];

if (response_code == 200) // Did the request succeed?
{
//Yes!
// Yes!
format(buffer, sizeof(buffer), "The URL replied: %s", data);
SendClientMessage(index, 0xFFFFFFFF, buffer);
}
else
{
//No!
// No!
format(buffer, sizeof(buffer), "The request failed! The response code was: %d", response_code);
SendClientMessage(index, 0xFFFFFFFF, buffer);
SendClientMessage(index, 0xFF0000FF, buffer);
}
}
```
Expand All @@ -83,4 +81,7 @@ As well as the response codes listed above, there are also all of the typical HT
:::
## Related Functions
## Related Information
- [HTTP Request Methods](../resources/http-request-methods)
- [HTTP Error Response Codes](../resources/http-error-response-codes)
67 changes: 67 additions & 0 deletions docs/scripting/resources/http-error-response-codes.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
---
title: HTTP Error Response Codes
description: HTTP error response codes.
---

:::note

These codes compliment ordinary [HTTP](../functions/HTTP) response codes returned in 'response_code'

:::

| Code | Error | Description |
|------|-------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 1 | HTTP_ERROR_BAD_HOST | Indicates that the URL used in an HTTP request is invalid or cannot be resolved by the DNS server. |
| 2 | HTTP_ERROR_NO_SOCKET | Indicates that there was a failure in establishing a network socket connection when making an HTTP request. |
| 3 | HTTP_ERROR_CANT_CONNECT | Indicates that the client is unable to establish a connection to the server when making an HTTP request. This error can occur due to various reasons, including network connectivity issues or unavailability of the server. |
| 4 | HTTP_ERROR_CANT_WRITE | Indicates that there was a failure in writing data during an HTTP request. This error can occur for various reasons related to the client, server, or network. |
| 5 | HTTP_ERROR_CONTENT_TOO_BIG | Indicates that the size of the content being sent in the HTTP request exceeds the maximum limit allowed by the server or the server's configuration. |
| 6 | HTTP_ERROR_MALFORMED_RESPONSE | Indicates that the HTTP response received from the server is in an unexpected or invalid format. This error suggests that the response does not comply with the HTTP protocol standards. |

## Some Common HTTP Error Response Codes

### 1xx Informational

| Code | |
|------|---------------------|
| 100 | Continue |
| 101 | Switching Protocols |
| 102 | Processing |

### 2xx Success

| Code | |
|------|-----------------|
| 200 | OK |
| 201 | Created |
| 204 | No Content |
| 206 | Partial Content |

### 3xx Redirection

| Code | |
|------|--------------------|
| 301 | Moved Permanently |
| 302 | Found |
| 304 | Not Modified |
| 307 | Temporary Redirect |

### 4xx Client Errors

| Code | |
|------|--------------------|
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
| 404 | Not Found |
| 405 | Method Not Allowed |
| 429 | Too Many Requests |

### 5xx Server Errors

| Code | |
|------|-----------------------|
| 500 | Internal Server Error |
| 502 | Bad Gateway |
| 503 | Service Unavailable |
| 504 | Gateway Timeout |
16 changes: 16 additions & 0 deletions docs/scripting/resources/http-request-methods.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
---
title: HTTP Request Methods
description: Types of HTTP request.
---

:::note

These request methods are used by [HTTP](../functions/HTTP) function.

:::

| ID | Method | Description |
|----|-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 1 | HTTP_GET | Sends a regular HTTP request.<br />GET request is used to read/retrieve data from a web server. GET returns an HTTP status code of **200 (OK)** if the data is successfully retrieved from the server. |
| 2 | HTTP_POST | Sends a HTTP request with POST data.<br />POST request is used to send data to the server. On successful creation, it returns an HTTP status code of **201**. |
| 3 | HTTP_HEAD | Sends a regular HTTP request, but ignores any response data - returning only the response code.<br />HEAD method is used to request the response headers for a specific resource without receiving the actual content of the resource. |
1 change: 1 addition & 0 deletions frontend/content/en/hello.txt
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Hey, what's up?

0 comments on commit 7e67375

Please sign in to comment.