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
  • Design flow
  • Resources
  • References

Was this helpful?

  1. Technical overview
  2. API Design Guide

Resource Oriented Design

PreviousPaginationNextREST Request

Last updated 2 years ago

Was this helpful?

API structure should follow Resource Oriented Design, which should facilitate simpler and more coherent web service interfaces, that should be easy to use and maintain. The data (resource) should control the design of the service, as the data is the key player and the service is centered around making the data accessible.

Design flow

The fundamental idea is that the basic, well-understood, and well-known technologies of the current web (HTTP, URI and XML) should be used according to their design principles. This facilitates the design of web services that have simple and coherent interfaces, and which are easy to use and maintain. Such web services will also be easier to optimize for working with the existing infrastructure of the web.

The Resource-Oriented Architecture (ROA) consists of four concepts:

  • Resources.

  • Their names (URIs).

  • Their representations.

  • The links between them and the four properties:

    • Addressability.

    • Statelessness.

    • Connectedness.

    • A uniform interface.

The Design Guide suggests taking the following steps when designing resource- oriented APIs.

  • Determine what types of resources an API provides.

  • Determine the relationships between resources.

  • Decide the resource name schemes based on types and relationships.

  • Decide the resource schemas.

  • Attach a minimum set of to resources. Use the standard methods(verbs) as much as possible.

Resources

A resource-oriented API is generally modelled as a resource hierarchy, where each node is either a simple resource or a collection resource. For convenience, they are often called a resource and a collection, respectively.

  • A collection contains a list of resources of the same type. For example, a user has a collection of photos.

  • A resource has some state and zero or more sub-resources. Each sub-resource can be either a simple resource or a collection resource.

A resource name consists of the resource’s type, its identifier, the resource name of its parent and the name of the API service. The type is known as the Collection ID, and the identifier is known as the Resource ID. Resource IDs are usually random strings assigned by the API service, though it is also OK to accept custom resource IDs from clients. Collection IDs must be the plural form of the noun used for the resource and Resource IDs should be immutable.

Below are two examples of valid resource names:

User

my-service.island.is/v1/users/1
\__________________/ | \____/ |
         |           |   |    |
         |           |   |     \
         |           |   |      Resource ID
         |           |    \
         |           |     Collection ID
         |           |        (type)
         |            \
         |             Major version
         \
          API service name

Photo

my-service.island.is/v1/users/1/photos/1
\__________________/ | \____/  \_____/ |
          |          |    |       |    |
          |          |    |       |     \
          |          |    |       |      Resource ID
          |          |    |       |        (type)
          |          |    |        \
          |          |    |         Collection ID
          |          |    |            (type)
          |          |     \
          |          |      Resource name of parent resource
          |           \
          |            Major version
          \
           API service name

References

methods
Google: Resource Oriented Design
Ratros Y: Designing APIs