REST API Pro Tips: Headers, HATEOAS, and When to Break the Rules - Part 4

https://giphy.com/gifs/chill-guy-new-character-qJzZ4APiDZQuJDY7vh

You’ve got your methods, routes, and status codes dialed in — nice.

Now it’s time to talk about the extra stuff that makes your API more professional, more secure, and (maybe) even a little delightful to use.

Let’s go.

Rule #1: Use Your Headers

HTTP headers are not just for browsers. Your API should lean into them — especially these:

Authorization

Used for tokens or keys:

Authorization: Bearer <your_token_here>

Content-Type

Make it explicit when sending JSON:

Content-Type: application/json

Accept

Use this when clients want to request a specific format or version:

Accept: application/json  
Accept: application/vnd.api.v2+json

Example: Basic Auth Middleware in Express

app.use((req, res, next) => {  
  const auth = req.headers.authorization;  
  if (!auth || !auth.startsWith('Bearer ')) {  
    return res.status(401).json({  
      error: {  
        code: 'UNAUTHORIZED',  
        message: 'Missing or invalid token'  
      }  
    });  
  }  
  // Validate token here...  
  next();  
});

Rule #2: HATEOAS — Know It, Don’t Overuse It

HATEOAS = Hypermedia as the Engine of Application State. Sounds fancy.

In practice? It means you include links in responses to guide the client on what to do next.

Example:

{  
  "id": 42,  
  "name": "Alice",  
  "links": [  
    { "rel": "self", "href": "/users/42" },  
    { "rel": "posts", "href": "/users/42/posts" }  
  ]  
}

✅ Helpful for discoverability
❌ Overkill for small/simple APIs
🔧 Great if you’re building an API-first product

Use it when it adds clarity, not just because a purist on Stack Overflow told you to.

Rule #3: When to Break the Rules (And When Not To)

REST is a guideline, not a religion. Sometimes, it’s okay to bend the rules — if you know why.

It’s okay to:

Use POST for complex queries that don’t fit into GET query params
Skip HATEOAS if you’re building for known clients
Mix in GraphQL or RPC-style endpoints if your use case demands it

It’s not okay to:

Use POST for everything just because it “works”
Make inconsistent route names
Ignore error handling or status codes

Rule #4: Cover Your Security Basics

Use HTTPS — always
Validate input — never trust client data
Rate-limit your endpoints
Don’t expose stack traces or internal errors
Log errors — consistently and securely

Even a small API can leak data if you’re sloppy.

Recap

Use headers properly (Authorization, Content-Type, etc.)
HATEOAS can be useful — but don’t let it bloat your response
Break the REST rules only when you have a good reason
Lock down your API like it’s production — because it probably is

That’s a Wrap!

You now know how to build a REST API that’s:

Clean and consistent
Easy to understand and use
Secure and scalable
Not annoying to maintain in six months

Catch the Full REST API Series