LogoLogo
  • Technical Direction
  • Technical overview
    • Technical Implementation
    • API Design Guide
      • Data Definitions and Standards
      • Data Transfer Objects
      • Documentation
      • Environments
      • Error Handling
      • Example API Service
      • GraphQL Naming Conventions
      • Methods
      • Naming Conventions
      • Once Only Principle
      • Pagination
      • Resource Oriented Design
      • REST Request
      • REST Response
      • Security
      • Versioning
    • Ísland.is Public Web Data Flow
    • Code Reviews
    • Code Standards
    • Monorepo
    • Project Management
    • Teamwork
    • Architectural Decision Records
      • Use Markdown Architectural Decision Records
      • Use NX
      • Continuous Integration
      • CSS
      • Branching and Release Strategy
      • Error Tracking and Monitoring
      • What API Management Tool to Consider
      • Viskuausan Static Site Generator
      • Use OAuth 2.0 and OpenID Connect As Protocols for Authentication and Authorization
      • Unified Naming Strategy for Files and Directories
      • CMS
      • Open Source License
      • What Chart Library Should We Use Across Island.is?
      • What Feature Flag Service/application Should We Use at Island.is?
      • Logging, Monitoring and APM Platform
      • ADR Template
    • Log Management Policy
  • Products
    • Island.is Authentication Service
      • Terminology
      • Integration Options
      • Authentication Flows
      • Authorising API Endpoints
      • Session Lifecycle
      • Scopes and Tokens
      • Delegations
      • Configuration
      • Tools and Examples
      • Environments
      • Test IAS with Postman
      • Using the IAS admin portal
    • Notifications / Hnipp
      • New Notification Setup Guide
      • Notifications service workflow overview
      • Email notifications
    • Pósthólfið
      • Security Checklist
      • Introduction
      • Skjalatilkynning API
      • Skjalaveita API
      • Sequence Diagram
      • Interfaces
    • Straumurinn (X-Road)
      • Architecture Guidelines for Service Providers and Consumers
      • Setting up an X-Road Security Server
        • Network Configuration
      • X-Road - Uppfærsla á öryggisþjónum
      • Straumurinn - Notkun og umsýsla
      • X-Road Central - current version
  • Development
    • Getting Started
    • Generating a New Project
    • Definition of done
    • Devops
      • Continuous Delivery
      • Database
      • Dockerizing
      • Environment Setup
      • Logging
      • Metrics
      • NextJS Custom Server
      • Observability
      • Operations Base Principles
      • Security
      • Service Configuration
      • Support
    • AWS Secrets
    • Feature Flags
    • Documentation Contributions
    • Defining Monorepo Boundaries With Tags
    • OpenAPI
    • Code Generation
    • Workspace Settings (Deprecated)
    • External Contributions
  • REFERENCE
    • Problems
      • 400 Validation Failed
      • 400 Attempt Failed
      • 403 Bad Subject
      • 400 500 Template API Error
    • Glossary
  • Misc
    • Guide: Adding a Payment Step to an Application
    • Guide: Enable Organisations to Make Requests to an Application
    • README Template
Powered by GitBook
On this page
  • Content Type
  • HTTP Status Codes
  • General
  • GET
  • POST
  • PUT
  • PATCH
  • DELETE

Was this helpful?

  1. Technical overview
  2. API Design Guide

REST Response

PreviousREST RequestNextSecurity

Last updated 11 months ago

Was this helpful?

A REST API should use an appropriate HTTP Status Code and Content Type when responding to a client's request.

Content Type

An API can support multiple response content types. It's preferred to use a JSON content type by default. When an API supports multiple content types the client can specify the desired content type with the .

The following table shows a list of common content types:

Content Type
Description

Default. Content type for a JSON response body.

Content type for a XML response body. Should be used when the XML is unreadable by casual users.

Content type for a XML response body. Should be used when the XML is readable by casual users.

When more details are needed in an error response the API should use an application defined errors and supply them in an in the response body.

In previous version of XML it said that text/xml was intended for XML content which a casual user is able to read, while application/xml is preferred when the XML content is unreadable by casual users.

HTTP Status Codes

REST APIs should use the range of to give the clients the most appropriate result of the request processing.

An API should at least use the following HTTP Status Codes for corresponding HTTP methods:

Code
Meaning
GET
POST
PUT
PATCH
DELETE

200

OK

X

X

X

X

201

Created

X

202

Accepted

X

204

No Content

X

X

X

X

303

See Other

X

400

Bad Request

X

X

X

401

Unauthorized

X

X

X

X

X

403

Forbidden

X

X

X

X

X

404

Not Found

X

X

X

X

X

500

Server error

X

X

X

X

X

General

  • 401 should be returned when client fails to authenticate.

  • 403 should be returned when client is authenticated but does not have necessary permission to perform the operation.

  • 404 should be returned when the static path of the request does not exist on the server.

GET

For retrieving a resource or a collection of resources.

  • 200 should be returned on success. If a collection asked for is empty or user does not have permission to access it, 200 is still to be returned with and empty array.

  • 204 should be returned when a single resource requested does not exist or the user does not have permission to access it.

When a parent resource of a sub-resource collection is not found or user does not have sufficient permissions the request should return 204 response.

POST

For creating a resource.

  • 201 should be returned when the resource was created. The response body should contain the created resource.

  • 202 should be returned when the request has been accepted for processing but may not have been acted upon or completed yet.

  • 400 should be returned if the request is invalid, i.e. the resource already exists or contains invalid fields.

PUT

For updating a existing resource.

  • 200 should be returned when resource is successfully updated with the updated resource in the response.

  • 204 should be returned when the resource is not found or the user does not have permission to update it.

  • 400 should be returned when the request is invalid, i.e. the resource contains invalid fields.

PATCH

For making a partial update on a resource.

  • 200 should be returned when resource is successfully updated with the updated resource in the response.

  • 204 should be returned when the resource is not found or the user does not have permission to update it.

  • 400 should be returned when the request is invalid, i.e. the resource contains invalid fields.

DELETE

For removing a resource.

  • 200 should be returned when the resource is deleted and there is a need for a content in the response.

  • 204 should be returned when the resource is deleted, does not exist or the user does not have permission to delete it and there is no content in response.

Content type for the for 4xx and 5xx statuse codes.

500 should be returned when the server encounters some unexpected error, preferably along with an object.

303 should be returned if the resource already exists on the resource server. The response should contain the header with the URI of the existing resource.

Accept header
error object
RFC3023
HTTP Status Codes
errors
Location
application/json
application/problem+json
Problem JSON error object
application/xml
text/xml