background preloader

URI Design

Facebook Twitter

RESTful Resource Naming. To insert (create) a new customer in the system, we might use: POST To read a customer with Customer ID# 33245: GET The same URI would be used for PUT and DELETE, to update and delete, respectively.

RESTful Resource Naming

Here are proposed URIs for products: POST for creating a new product. GET|PUT|DELETE for reading, updating, deleting product 66432, respectively. Now, here is where it gets fun... What about creating a new order for a customer? Because we want to create an order for a customer (note the relationship), this URI perhaps is not as intuitive as it could be. Now what would the following return? Now, to continue the hierarchical concept, what about the following URI? Along those lines, because there may be multiple URIs for a given resource, we might also offer a GET URI that supports retrieving an order by number without having to know the customer number.

Common REST Design Pattern. Based on the same architectural pattern of the web, "REST" has a growing dominance of the SOA (Service Oriented Architecture) implementation these days.

Common REST Design Pattern

In this article, we will discuss some basic design principles of REST. SOAP : The Remote Procedure Call Model Before the REST become a dominance, most of SOA architecture are built around WS* stack, which is fundamentally a RPC (Remote Procedure Call) model. Under this model, "Service" is structured as some "Procedure" exposed by the system. REST API Design - Resource Modeling. “The key abstraction of information in REST is a resource.

REST API Design - Resource Modeling

Any information that can be named can be a resource: a document or image, a temporal service (e.g. "today's weather in Los Angeles"), a collection of other resources, a non-virtual object (e.g. a person), and so on. In other words, any concept that might be the target of an author's hypertext reference must fit within the definition of a resource. A resource is a conceptual mapping to a set of entities, not the entity that corresponds to the mapping at any particular point in time.” - Roy Fielding’s dissertation.

Resources form the nucleus of any REST API design. A resource can be a singleton or a collection. The starting point in selection of resources is to analyze your business domain and extract the nouns that are relevant to your business needs. However, this simplistic approach may be valid at an abstract level, but breaks down once you hit more complicated domains in practice. Escaping CRUD Nouns versus Verbs. Best Practices for Designing a Pragmatic RESTful API. Your data model has started to stabilize and you're in a position to create a public API for your web app. You realize it's hard to make significant changes to your API once it's released and want to get as much right as possible up front. Now, the internet has no shortage on opinions on API design.

But, since there's no one widely adopted standard that works in all cases, you're left with a bunch of choices: What formats should you accept? How should you authenticate? Atlassian REST API Design Guidelines version 1 - Atlassian Developers. This document provides guidelines to Atlassian developers who are designing REST APIs for Atlassian applications.

Atlassian REST API Design Guidelines version 1 - Atlassian Developers

We are publishing these design principles and guidelines for viewing by the wider community for these reasons: If you are a developer/administrator who wants to interact with the REST API in one or more of the Atlassian applications, it will help you to know the principles behind our REST API design.If you are developing a plugin that exposes a REST API, you can follow these guidelines to ensure consistency between your plugin and the host application's APIs.We invite and welcome feedback on these design principles. Document version control The design guidelines are under version control. Any significant changes to the guidelines will undergo review and approval and will be published under a new version number, as reflected in the page title.

Secure Software Development. There is a lot of interest in REST APIs these days.

Secure Software Development

Unfortunately, most APIs I see are not very mature. In this post I’d like to share my approach to designing REST APIs: Understand the problem domain and application requirements and document them as a state diagramDiscover the resources from the transitionsName the resources with URIsSelect one or more media types to serialize the various representations identified in the resource modelAssign link relations to each of the transitionsAdd documentation as required. SOA2009-REST-Patterns.pdf.

Untitled. Web services - Hierarchical RESTful URL design. REST-ful URI design. This post is about URI naming.

REST-ful URI design

Designing URI names. Some tips and rules and conventions that you can follow when figuring out your application’s URIs. The focus is on URIs for ‘REST-ful’ applications. But many of the tips apply to any kind of website or application. URI design on your REST Web API - Michel Triana. This is a follow up post to “Using HTTP Status Codes correctly in your REST Web API”, and “Using HTTP Verbs correctly in your REST Web API”.

URI design on your REST Web API - Michel Triana

Continuing with the theme of RESTful Web APIs, I thought I would touch on the importance of the actual URL/URI part of the Web API. One way we can think of our Web API is as a database exposed through the HTTP layer. Like any good database, we must be careful when designing “the DB model of our Web API“. The equivalent to a formal DB Model (ERD for relational databases), is the Resource Modeling that goes into the Web API. Let’s dive right in.