Category: Rest

Building a Proper REST API with authentication


First thing we need to be clear about is your method of authentication means nothing if you are not using https. If you are not using https then your users credentials can be snooped.

What is REST?

TL;DR Cheat sheet

Representation State Transfer

Resource based

we are talking about thing(nouns) instead of actions(verbs)

resource is identified by the URI

The representation is not the resource, it is just a representation.


How resources get manipulated.

Part of the resource state.



Resource: person

Service: contact_info GET

Representation: name, address, phonenumber (JSON/XML)

6 Constraints

Violating any of these except the optional code on demand, means your API is not strictly RESTful

Uniform Interface

A consistent interface between client and server


Uri's: Resource names

HTTP Response: status, body


Server contains no client state, each request has enough context for server to process in isolation

If there is state, it is kept on the client side


Assume a disconnected system

Separation of concerns


Server response for representations


Explicit - server specifies

Negotatiated - client and server negotiate

Layered System

Client does not assume direct connection

You don't know where or how you are getting the data


Code on Demand

Server can temporararily extend a client, transfer logic to client

Client executes logic

An optional constraint

Rest API Allows

  • Scalability
  • Simplicity
  • Modifiability
  • Visibility
  • Portability
  • Reliability


HTTP Verbs similarity with CRUD





Use URL not query string

  • Good: /users/12345
  • Poor: /api?type=user&id=23

Design for your clients not your data

Use Plurals for consistency


  • Recommended: /customers/33245/orders/8769/lineitems/1
  • Not: /customer/33245/order/8769/lineitem/1

Use the correct HTTP Status Code Responses

Offer JSON and XML

Use hypermedia links

A key concept that is central to the idea of what REST really is.

Hypermedia links (HATEOS)  or Hypermedia as the Engine of Application State make services more discoverable and self-descriptive

The client needs no prior knowledge about resources etc.

Documentation should not be a requirement to understand the API

So you can browse an API just like browsing the web <- that is restful

Client should not need to know how to interact with the data (hardcoded urls / resource names), the server should know this

So you can allow the html media type and you can really browse the api like you do the web

Effort required increases

Likely Requests and Responses

A list of HTTP methods and responses

Naming Resources

Use nouns

They should be predictable

Choose for clients not your data

Plurals: it is a debate but rather always user them


Basically an action can be applied to an object multiple times but applying it more than once will not change the state or result of it's application.

Eg. Getting a cow pregnant

A GET never changes data so it is idempotent (Safe method)

PUT is idempotent as it updates an object with the same data, will return the same result

DELETE is idempotent, it will return a 404 - NB. It is better to mark for deletion instead of actually deleting

POST is NOT idempotent, as for every new POST there is a new different result




What is REST tutorial

Oauth2 vs Json Web Tokens

Headers sent but not received by Application, Shopify and Restful API’s

I was tasked with creating a service (app) that would interact with the ShopifyAPI.

To create the service the flow would be:

  1. Authenticate (Oauth)
  2. Register the Service with callback url
  3. Return relevant data when Shopify makes the external call (webhook)

This is the first time I had worked with Oauth and a Restful API. What I didn't know was that the header information of HTTP requests often contain important information so we need to be able to get and set these values in our application development.

Furthermore for testing purposes I initially had to use curl as the client making the calls to the API. This was unintuitive in terms of setting headers and everything and then viewing and checking the response. That is when a senior developer advised that the use of a REstful client from within your browser should be used, he advised the use of Postman: a restful Client.

With postman you can easily and intuitively set the HTTP payload (often JSON) and header information. The webhook coming from Shopify will send the following header:


To identity the shop. Now to test this request with Postman, I added a header and typed in exactly that:


But an error was that the header was never sent to the application. What was going wrong?

Well I know it was being sent by checking the network tab of the developer tools. But it was not being received (or was being parsed or mutated) by either apache or php.

Eventually I found out that apache does not accept "_" underscores in HTTP headers. It will remove them, however it will convert dashes to underscores. So the header should have looked like this:


The full reason behind this can be found here: Why underscores are forbidden in HTTP header names