Thoughts on RESTful API design Read the Docs

Thoughts On Restful Api Design Read The Docs-Free PDF

  • Date:27 Oct 2020
  • Views:2
  • Downloads:0
  • Pages:25
  • Size:231.91 KB

Share Pdf : Thoughts On Restful Api Design Read The Docs

Download and Preview : Thoughts On Restful Api Design Read The Docs


Report CopyRight/DMCA Form For : Thoughts On Restful Api Design Read The Docs


Transcription:

1 Lessons learnt from designing the Red Hat Enterprise Virtualization API 1. 1 1 Introduction 1,1 2 The Job of the API Designer 2. 1 3 Resources 3,1 4 URLs 8,1 5 Methods 10,1 6 Relationships 13. 1 7 Forms 14,1 8 Miscellaneous Topics 19, Lessons learnt from designing the Red Hat Enterprise Virtualization API. Author Geert Jansen gjansen redhat com,Date November 15th 2012. This work is licensed under a Creative Commons Attribution 3 0 Unported License. The source of this document can be found on github. 1 1 Introduction, This essay is an attempt to put down my thoughts on how to design a real world yet beautiful RESTful API It.
draws from the experience I have gained being involved in the design of the RESTful API for Red Hat s Enterprise. Virtualization product twice During the design phase of the API we had to solve many of the real world problems. described above but we weren t willing to add non RESTful or RPC like interfaces to our API too easily. In my definition a real world RESTful API is an API that provides answers to questions that you won t find in. introductory texts but that inevitably surface in the real world such as whether or not resources should be described. formally how to create useful and automatic command line interfaces how to do polling asynchronous and other. non standard types of requests and how to deal with operations that have no good RESTful mapping. A beautiful RESTful API on the other hand is one that does not deviate from the principles of RESTful architecture. style too easily One important design element for example that is not always addressed is the possibility for complete. auto discovery by the API user so that the API can be used by a human with a web browser without any reference to. external documentation I will discuss this issue in detail in Forms. This essay does not attempt to explain the basics about REST as there are many other texts about that For a good. description of REST I would recommend reading at least the Atom Publishing Protocol and this blog post by Roy. While the views exposed in this essay are my own they are heavily based on the public discussion on the rhevm. api mailing list My thanks goes to all people who have contributed and are still contributing to it including Mark. McLoughlin Michael Pasternak Ori Liel Sander Hoentjen Ewoud Kohl van Wijngaarden Tomas V V Cox and. everybody else I forgot,Thoughts on RESTful API design Release 1 0. 1 2 The Job of the API Designer, Before we dive fully into RESTful API design it makes sense to look in a little more detail what the job of a RESTful. API designer is, APIs don t exist in isolation Instead APIs expose functionality of an application or service that exists independently. of the API In my view the job of the RESTful API designer is two fold. 1 Understanding enough of the important details of the application for which an API is to be created so that an. informed decision can be made as to what functionality needs to be exposed how it needs to be exposed and. what functionality can instead be left out, 2 Modeling this functionality in an API that addresses all use cases that come up in the real world following the. RESTful principles as closely as possible, There are three distinct components involved in RESTful API design the application the API code and the client.
The image above illustrates how these three components interact. 1 2 1 The Application, The application for which an API is to be provided exists independently of that API Maybe the application has a GUI. and you have a requirement to add a programmatic interface to it Or maybe the application was designed under the. assumption that it would be accessed only via the API you are designing. Like any application the application for which the API is to be created contains state That state is dynamic and will. change due to various operations that are executed on it This state and the operations on it need to be modeled and. exposed and will form the API you are designing, The easiest way to think about the application state is to assume that it is is described by an application data model. which can be described by an Entity Relationship diagram The ER Diagram lists the details of the entities I will call. them objects in the application state and the relationships between them. In some cases it is very easy to create the ER diagram For example in case of a web application that stores all its. state in a database it can be trivially created from the schema of the database In other cases where there is not such. a precise definition the job of the API designer becomes a little more difficult In such a case it would actually make. sense to create an ER diagram for the application in question That is a useful exercise in its own right as it will. make you better understand the application you re designing the API for But more importantly it will also help you. in designing a good RESTful API We will talk more about that in a minute Going forward I will assume that an ER. diagram is available, 2 Chapter 1 Lessons learnt from designing the Red Hat Enterprise Virtualization API. Thoughts on RESTful API design Release 1 0, In addition to understanding the application data model and the operations on it you of course need an entry point into. the application that allows you to access and change the application state This way in is fully application dependent. and could take many forms We will call this way in the application interface Formally this application interface. could be considered an API as well The difference though is that this interface is usually not intended for external. consumption or even fully documented In order not to introduce any confusion we will not refer to this interface as. an API that term will be reserved for the RESTful API that is being designed. 1 2 2 The API Code, The job of the API code is to access the application state as well as the operations on that state via the application.
interface and expose it as a RESTful API In between the application interface and the RESTful API there is a. transformation step that adapts the application data model and makes it comply with the RESTful architecture style. The result of this transformation would be RESTful resources operations on those resources and relationships be. tween the resources All of these are described by what we call the RESTful resource model. Resources are the foundation behind any RESTful API and we will go into a lot of detail on them in Resources For. now just think of resources as being very similar to the entities from the ER diagram which is why I encouraged you. to create an ER diagram for your application in case it didn t exist. Relationships between resources are expressed as hyperlinks in the representation of the resource This is one of the. fundamental principles of RESTful API design Resources also respond to a very limited set of operations usually. just 4 which is a second principle of the RESTful architectural style. When transforming objects from the application data model to RESTful resources you may find it useful to define. two utility functions,to resource, This function is assumed to take an object from the application data model and convert it into a resource. from resource, This function is assumed to take a resource and translate it into an object in the application data model. We don t discuss these methods further other than mentioning that these can be rather simple functions if the ap. plication data model is similar to the resource model you re exposing and can be quite complicated if they are very. 1 2 3 The Client, The client consumes the RESTful API via the standard HTTP protocol In theory the service could be provided on. top of other protocols as well Since HTTP is so ubiquitous however it is not certain how valuable such a mapping to. another protocol would be in the real world Therefore this essay limits itself to describing our RESTful protocol in. terms of HTTP, Clients would typically use an HTTP library to access the RESTful API HTTP has become a moderately complex. protocol and very good libraries exist for many target platforms languages It therefore makes a lot of sense to use. one of those libraries, In some cases it may make sense to use a generic REST library on top of an HTTP library However since there are so.
many different conventions in RESTful APIs this library may actually be specific to the API that you are consuming. 1 3 Resources, The fundamental concept in any RESTful API is the resource A resource is an object with a type associated data. relationships to other resources and a set of methods that operate on it It is similar to an object instance in an object. 1 3 Resources 3,Thoughts on RESTful API design Release 1 0. oriented programming language with the important difference that only a few standard methods are defined for the. resource corresponding to the standard HTTP GET POST PUT and DELETE methods while an object instance. typically has many methods, Resources can be grouped into collections Each collection is homogeneous so that it contains only one type of. resource and unordered Resources can also exist outside any collection In this case we refer to these resources as. singleton resources Collections are themselves resources as well. Collections can exist globally at the top level of an API but can also be contained inside a single resource In the. latter case we refer to these collections as sub collections Sub collections are usually used to express some kind of. contained in relationship We go into more detail on this in Relationships. The diagram below illustrates the key concepts in a RESTful API. We call information that describes available resources types their behavior and their relationships the resource model. of an API The resource model can be viewed as the RESTful mapping of the application data model. 1 3 1 Resource Data, Resources have data associated with them The richness of data that can be associated with a resource is part of the. resource model for an API It defines for example the available data types and their behavior. Based on my experience I have developed a strong conviction that the JSON data model has just the right richness. so that it is an ideal data model for RESTful resources I would recommend that everybody use it. In JSON just three types of data exist,scalar number string boolean null.
Scalar types have just a single value Arrays contain an ordered list of values of arbitrary type Objects consist of a. unordered set of key value pairs also called attributes not to be confused with XML attributes where the key is a. string and the value can have an arbitrary type For more detailed information on JSON see the JSON web site. Why the strong preference for JSON In my view JSON has the right balance between expressiveness and broad. availability The three types of data scalars arrays and objects are powerful enough to describe in a natural way. 4 Chapter 1 Lessons learnt from designing the Red Hat Enterprise Virtualization API. Thoughts on RESTful API design Release 1 0, virtually all the data that you might want to expose as resource and at the same time these types are minimal enough. so that almost any modern language has built in support for them. XML would be the other obvious contender Actually in the final incarnation of the RHEV M API XML is used to. describe resources via an XMLSchema definition With hindsight I believe that the XML data model is a bad choice. for a RESTful API On one side it is too rich and on the other side it lacks features XML as an SGML off shoot is. in my view great for representing structured documents but not for representing structured data. Features of XML that are too rich include, 1 Attributes vs elements An XML element can have both attributes as well as sub elements A data item associ. ated with a resource could be encoded in either one and it would not be clear beforehand which one a client or. a server should use, 2 Relevance of order The order between child elements is relevant in XML It is not natural in my view for object. attributes to have ordering,The limitations of the XML data model are. 1 Lack of types Elements in XML documents do not have types and in order to use types one would have to use. e g XMLSchema XMLSchema unfortunately is a strong contender for the most convoluted specification ever. 2 Lack of lists XML cannot natively express lists This can lead to issues whereby it is not clear whether a certain. element is supposed to be a list or an object and where that element ends up being both. Application Data, We define the data that can be associated with a resource in terms of the JSON data model using the following mapping.
1 Resources are modeled as a JSON object The type of the resource is stored under the special key value pair. 2 Data associated with a resource is modeled as key value pairs on the JSON object To prevent naming conflicts. with internal key value pairs keys must not start with. 3 The values of key value pairs use any of the native JSON data types of string number boolean null or arrays. thereof Values can also be objects in which case they are modeling nested resources. 4 Collections are modeled as an array of objects, We will also refer to key value pairs as attributes of the JSON object and we will be sloppy and use that same term. for data items associated with resources too This use of attributes is not to be confused with XML attributes. Thoughts on RESTful API design Release 1 0 In addition to understanding the application data model and the operations on it you of course need an entry point into the application that allows you to access and change the application state This way in is fully application dependent and could take many forms We will call this way in

Related Books