REST API: the complete guide for beginner developers

You’re new to development and the term REST API seems abstract? You’re not alone. According to Stack Overflow, 65% of junior developers consider APIs one of the most difficult concepts to master initially. Yet, REST APIs are everywhere: every application you use consumes or exposes one.

In this guide, you’ll understand what a REST API is, how it works, and how to use it concretely in your projects. Code examples included.

What is a REST API?

Simple definition

An API (Application Programming Interface) is a set of rules that allows two applications to communicate with each other. REST (Representational State Transfer) is an architectural style that defines how this communication should be organized.

Imagine a restaurant:

• The customer (your application) places an order
• The waiter (the API) transmits the order to the kitchen
• The kitchen (the backend server) prepares the dish
• The waiter brings the dish back to the customer

The REST API plays the role of the waiter: it receives requests, processes them, and returns responses.

Why REST dominates the web

REST has established itself as the standard for web APIs for several reasons:

• Simplicity: uses HTTP methods you already know
• Flexibility: works with any programming language
• Scalability: stateless architecture that scales easily
• Standardization: conventions shared by all developers

According to ProgrammableWeb, more than 83% of public APIs use REST architecture in 2025.

The 6 fundamental principles of REST

For an API to be considered “RESTful,” it must respect these constraints:

1. Client-server architecture

The client and server are separate and independent. The client doesn’t care about data storage. The server doesn’t care about the user interface.

Advantage: each part can evolve independently.

2. Stateless

Each request contains all the information needed for its processing. The server retains no session information between requests.

Example: you must send your authentication token with each request.

3. Caching

Responses must indicate whether they can be cached. This improves performance and reduces server load.

4. Uniform interface

The API uses standardized conventions:

• Resource identification via URIs
• Manipulation through representations (JSON, XML)
• Self-descriptive messages
• Hypermedia as the engine of application state (HATEOAS)

5. Layered system

The client doesn’t know if it’s communicating directly with the server or through an intermediary (load balancer, cache, proxy).

6. Code on demand (optional)

The server can send executable code to the client (JavaScript for example).

Essential HTTP methods

REST APIs use HTTP verbs to define the action to perform on a resource.

GET: read data

Retrieves a resource without modifying it.

GET /api/contacts/123

Response: the data for contact 123.

POST: create a resource

Sends data to create a new resource.

POST /api/contacts
Content-Type: application/json

{
  "name": "Marie Dupont",
  "email": "[email protected]"
}

Response: the created resource with its identifier.

PUT: replace a resource

Completely replaces an existing resource.

PUT /api/contacts/123
Content-Type: application/json

{
  "name": "Marie Martin",
  "email": "[email protected]",
  "phone": "0612345678"
}

PATCH: partially modify

Updates only certain fields of a resource.

PATCH /api/contacts/123
Content-Type: application/json

{
  "phone": "0687654321"
}

DELETE: delete

Deletes a resource.

DELETE /api/contacts/123

HTTP status codes to know

Each API response includes a status code. Here are the most common:

2xx codes: success

Code	Meaning	Usage
200	OK	Successful request
201	Created	Resource created (POST)
204	No Content	Success without content (DELETE)

4xx codes: client error

Code	Meaning	Cause
400	Bad Request	Malformed request
401	Unauthorized	Authentication required
403	Forbidden	Access denied
404	Not Found	Resource doesn’t exist
422	Unprocessable Entity	Invalid data

5xx codes: server error

Code	Meaning	Cause
500	Internal Server Error	Server-side error
502	Bad Gateway	Failing intermediate server
503	Service Unavailable	Service temporarily unavailable

Practical example: consuming a REST API

Let’s see how to interact with a REST API in JavaScript.

Retrieve data (GET)

async function getContacts() {
  const response = await fetch('https://api.example.com/contacts', {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer your_api_token',
      'Content-Type': 'application/json'
    }
  });

  if (!response.ok) {
    throw new Error(`HTTP error: ${response.status}`);
  }

  const contacts = await response.json();
  return contacts;
}

Create a resource (POST)

async function createContact(contactData) {
  const response = await fetch('https://api.example.com/contacts', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer your_api_token',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(contactData)
  });

  if (!response.ok) {
    throw new Error(`HTTP error: ${response.status}`);
  }

  const newContact = await response.json();
  return newContact;
}

// Usage
const contact = await createContact({
  name: 'Jean Durand',
  email: '[email protected]'
});

Handle errors properly

async function safeApiCall(url, options) {
  try {
    const response = await fetch(url, options);

    if (response.status === 401) {
      // Token expired, redirect to login
      window.location.href = '/login';
      return;
    }

    if (response.status === 404) {
      return null; // Resource not found
    }

    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.message || 'Unknown error');
    }

    return await response.json();
  } catch (error) {
    console.error('API error:', error);
    throw error;
  }
}

Best practices for designing a REST API

If you’re creating your own API, follow these conventions.

Name resources correctly

Use nouns, not verbs. Use plurals.

Correct:

• GET /contacts: list of contacts
• GET /contacts/123: a specific contact
• POST /contacts: create a contact

Incorrect:

• GET /getContacts
• POST /createContact
• GET /contact/123

Structure URLs logically

For relationships between resources:

GET /organizations/456/contacts      # Contacts of an organization
GET /contacts/123/messages           # Messages from a contact
POST /forms/789/submissions          # Create a form submission

Version your API

Allow evolution without breaking existing clients:

https://api.example.com/v1/contacts
https://api.example.com/v2/contacts

Paginate lists

Never return all results at once:

GET /contacts?page=2&limit=20

Response with pagination metadata:

{
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 20,
    "total": 156,
    "pages": 8
  }
}

Filter and sort

Allow clients to refine their queries:

GET /contacts?status=active&sort=-created_at&fields=name,email

REST API authentication

Several methods exist to secure your APIs.

API Key

Simple and effective for server-to-server integrations:

GET /contacts
X-API-Key: sk_live_abc123def456

Bearer Token (OAuth 2.0)

Standard for modern applications:

GET /contacts
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

When to use what?

Method	Use case
API Key	Backend integrations, webhooks
OAuth 2.0	Third-party applications, mobile
JWT	User authentication

Skedox offers all three authentication methods to adapt to all your integration needs. Whether you’re connecting a CRM, an automation tool, or a custom application, you’ll find the right method.

Tools for testing your REST APIs

Postman

The reference tool for testing and documenting your APIs. Intuitive graphical interface, shared collections, automated tests.

cURL

On the command line, quick for one-off tests:

curl -X GET "https://api.example.com/contacts" \
  -H "Authorization: Bearer your_token" \
  -H "Content-Type: application/json"

Insomnia

Open source alternative to Postman. Clean interface, native GraphQL support.

Browser extension

REST Client for VS Code allows testing directly from your editor.

Concrete case: integrating the Skedox API

Here’s how to retrieve your form submissions via the Skedox REST API.

Authentication

Generate your API key in Settings > Integrations > API Keys.

Retrieve submissions

const response = await fetch('https://api.skedox.com/v1/forms/abc123/submissions', {
  headers: {
    'Authorization': 'Bearer sk_live_your_key',
    'Content-Type': 'application/json'
  }
});

const submissions = await response.json();

Webhook for real-time

To receive submissions instantly, configure a webhook:

// Your endpoint automatically receives new submissions
app.post('/webhook/skedox', (req, res) => {
  const submission = req.body;

  // Process the submission (create a CRM contact, send an email...)
  processSubmission(submission);

  res.status(200).send('OK');
});

Discover all integration possibilities in the Skedox documentation.

Common beginner mistakes

1. Ignoring status codes

Don’t just check response.ok. Handle each code appropriately.

2. Forgetting network error handling

Requests can fail before even reaching the server:

try {
  const response = await fetch(url);
} catch (error) {
  // Network error (no connection, DNS, timeout...)
  console.error('Unable to reach the server');
}

3. Exposing API keys client-side

Never put your API keys in browser-side JavaScript code. Use a backend or serverless functions.

4. Not versioning

Without versioning, each modification can break existing clients.

5. Neglecting documentation

An API without documentation is unusable. Use OpenAPI/Swagger to generate automatic documentation.

Conclusion: master REST APIs to progress

REST APIs are the universal language of the modern web. As a beginner developer, mastering them opens the doors to service integration, automation, and connected application development.

Remember the essential points:

• REST uses HTTP verbs (GET, POST, PUT, DELETE)
• Each resource has a unique URL
• Status codes indicate the request result
• Authentication secures exchanges
• Documentation is essential

To practice, start by consuming an existing API. Test with Postman. Then create your first integrations.

Ready to connect your tools and automate your workflows? Skedox offers a complete and documented REST API to integrate your forms, feedback, and newsletters into your technical stack. Create your free account and explore integration possibilities right now.