What Is REST API ?

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, and DELETE
• 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": "[e-mail]"
}

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: "[e-mail]",
    }

    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": "[e-mail]"
}

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: "[e-mail]",
    }

    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.