Ciao, I'm Julia.

I’ve been doing more backend programming recently and was assigned a feature that required poking around in some API endpoints. It got me thinking about API design and the different approaches to how APIs transfers data from servers to clients and vice versa. In my engineering career to date, I’ve mostly dealt with REST APIs, but have also recently started dipping my toes into GraphQL APIs. I therefore wanted to read up on the topic to confirm what I think I know about the topic, and write a blog post to solidify my understanding. ✌🏻

REST: REpresentation State Transfer

• A set of architectural principles / guidelines, primarily for the development of APIs facilitating data transfer between web services and clients.
  • Flexible implementation, likely resulting in faster, more lightweight APIs.
• REST is so called because it gives the client access to a representation of the state of a desired resource.
• Requests sent to a REST API is normally done through hypertext transfer protocol (HTTP).
  • Uses Uniform Resource Identifier (URIs) to access resources, along with an HTTP operation (GET, POST, PUT, DELETE).
• Responses can take a range of formats, e.g. HTML, XML, plain text and JSON. JSON is the most flexible and thus most favoured.
• The 6 architectural principles that make a RESTful application are:
  • That it is composed of clients, servers and resources.
  • Stateless communication - information about a session’s state is stored by the client, not the server.
    • Client must provide all necessary information in every session including authentication details.
  • Cacheable data.
  • Uniform interface allowing information to be transferred in a standardised form to any client applications.
  • Capable of having independent hierarchical layers between client and server (layered system).
    • e.g. important for load balancing cache sharing
  • [Optional] Servers transferring executable code (code on demand), allowing extension of client functionality.

SOAP: Simple Object Access Protocol

• A protocol with built-in rules and standards, including security and ACID (atomicity, consistency, isolation and durability - for ensuring reliable database transactions).
  • Specific requirements needed for requests and transfer of information, which might thus be better for enterprise needs.
• Less lightweight, and can result in longer page load times, due to in-built rules adding complexity and overhead.
  • Requires more bandwidth vs. REST due to size of messages that need to be transferred.
• Requests can be sent via any of the application layer protocols i.e. HTTP (web apps), SMTP (email clients), TCP etc. (protocol agnostic).
  • Uses service interfaces to expose application logic (ideal for performing operations).
• Responses must take the form of XML (markup language).
• Requests are not cacheable.
• Bonus fact: Created by Microsoft.

GraphQL

• Data fetching specification that is also an API query language.
• Does not deal with dedicated resources. It instead considers all resources to be connected in a graph (rather than rows and columns in a relational database for instance).
• Allows for flexible requests that define all resource requirements for a task, with responses that are returned only with the information we require.
  • Limits the number of API calls needed when compared to REST.
• If called via HTTP, it always provides a 200 OK response status regardless of outcome.
  • Use HTTP POST for querying and mutations.
• No data caching.
• More complex to set up compared to REST.
• Bonus fact: Created by Facebook.

When to use SOAP over REST or GraphQL?

• If your API needs to be highly secure and you want to design to strong standards.
• If you need to be able to store state between requests.

When to use REST over SOAP?

• If you have a publicly available API.
• If you need something lightweight and easy to set up.
• If you need to minimise bandwidth used for data transfer.

When to use REST over GraphQL?

• If you have a small application and don’t want the overhead of setting up complex GraphQL querying.
• If you have a resource driven app that doesn’t require flexible queries.

When to use GraphQL over REST or SOAP?

• If you need to query for multiple resources at once and don’t want to make multiple API calls to fulfil a single task.
• If you want to be able to define exactly what you want returned in the response.

Bonus: How does CRUD fit into all this

• When designing APIs, we want it to be able to do, at most, 4 basic database commands to a model, which when put together, makes CRUD:
  • Create
  • Read
  • Update
  • Delete
• CRUD actions allow us to maintain database records, thus making models usable.
• If an action does not fall within one of these operations, it should potentially be a model of its own.
• CRUD often corresponds to the following HTTP methods in a RESTful application:
  • Create - POST
  • Read - GET
  • Update - PUT or PATCH
  • Delete - DELETE
• Some programming languages have their own version of CRUD with slight modifications.
  • SQL: Insert, Select, Update, Delete