A REST API (Representational State Transfer API) enables communication between a client and a server over HTTP. It exchanges data — typically in JSON format — using standard web protocols, making it one of the most widely adopted architectural styles for building web services today.
If you're wondering what is HTTP method or what is HTTP at all, you can check my previous article What Is HTTP & HTTPS ?.
Key characteristics of a REST API:
- Uses standard HTTP methods:
GET,POST,PUT, andDELETE - The client sends requests to server endpoints (URLs)
- The server responds with the requested data in formats like JSON, XML, HTML, or binary (e.g., images)
Note: REST is an architectural style that defines how APIs should be designed, whereas HTTP is the protocol used to transfer data. They work together, but they are not the same thing.
Common HTTP Methods
1. GET
GET is used to retrieve data from the server without modifying anything. It is idempotent — calling it multiple times produces the same result.
Common response codes:
| Status Code | Meaning |
|---|---|
200 OK |
Data found and returned successfully |
404 Not Found |
The requested resource does not exist |
400 Bad Request |
The request was malformed |
Example request:
GET /users/123
This request fetches the data for the user with ID 123.
Go implementation:
package main
import (
"fmt"
"net/http"
)
func main() {
client := &http.Client{}
url := "https://api.example.com/users/123"
req, err := http.NewRequest(http.MethodGet, url, nil)
if err != nil {
panic(err)
}
req.Header.Set("Content-Type", "application/json")
resp, err := client.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
fmt.Printf("Response Status: %s\n", resp.Status)
}
2. POST
POST is used to create a new resource on the server. On success, it returns 201 Created, often with a Location header pointing to the newly created resource.
Example request:
POST /users
Content-Type: application/json
{
"name": "Anne",
"email": "anne@example.com"
}
This request creates a new user with the provided data.
Go implementation:
package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
)
type User struct {
Name string `json:"name"`
Email string `json:"email"`
}
func main() {
url := "https://api.example.com/users"
user := User{
Name: "Anne",
Email: "anne@example.com",
}
jsonData, err := json.Marshal(user)
if err != nil {
panic(err)
}
resp, err := http.Post(url, "application/json", bytes.NewBuffer(jsonData))
if err != nil {
panic(err)
}
defer resp.Body.Close()
fmt.Printf("Response Status: %s\n", resp.Status)
}
3. PUT
PUT is used to update an existing resource or create it if it does not exist. Unlike PATCH, it requires the complete resource to be sent in the request body — it replaces the resource entirely.
Example request:
PUT /users/123
Content-Type: application/json
{
"name": "Anne",
"email": "anne@example.com"
}
This request updates the user with ID 123, or creates a new one if that user does not exist.
Go implementation:
package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
)
type User struct {
Name string `json:"name"`
Email string `json:"email"`
}
func main() {
client := &http.Client{}
url := "https://api.example.com/users/123"
user := User{
Name: "Anne",
Email: "anne@example.com",
}
jsonData, err := json.Marshal(user)
if err != nil {
panic(err)
}
req, err := http.NewRequest(http.MethodPut, url, bytes.NewBuffer(jsonData))
if err != nil {
panic(err)
}
req.Header.Set("Content-Type", "application/json")
resp, err := client.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
fmt.Printf("Response Status: %s\n", resp.Status)
}
4. DELETE
DELETE is used to remove a resource identified by its URI. On successful deletion, the server returns 200 OK (with a response body) or 204 No Content (with no body).
Example request:
DELETE /users/123
This request deletes the user with ID 123.
Go implementation:
package main
import (
"fmt"
"net/http"
)
func main() {
client := &http.Client{}
url := "https://api.example.com/users/123"
req, err := http.NewRequest(http.MethodDelete, url, nil)
if err != nil {
panic(err)
}
req.Header.Set("Content-Type", "application/json")
resp, err := client.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
fmt.Printf("Response Status: %s\n", resp.Status)
}
Summary
| Method | Purpose | Success Code |
|---|---|---|
GET |
Retrieve a resource | 200 OK |
POST |
Create a new resource | 201 Created |
PUT |
Update or replace a resource | 200 OK |
DELETE |
Remove a resource |
200 OK / 204 No Content
|
Understanding these four methods covers the majority of real-world REST API interactions. In a future article, we'll dive into PATCH (partial updates), authentication with API keys and JWT, and how to handle errors properly on both the client and server sides
REST is powerful, but what if the server could give you exactly what you ask for — nothing more, nothing less? That's the promise of GraphQL. Next up, we break it down.