RESTful Design is the process of developing a system of resources that behave in a RESTful way. This page is intended to describe a specific approach which I have found useful. RESTful Design consists of a number of steps. These steps vary in the level of technical and social complexity involved. (5ZQ)
The design process consists of two basic diagrams: (60G)
Architecture (5ZR)
The architecture diagram is the context of your RESTful Design. It lists all of the software components that need to interact with each other, and the interfaces between them. I like to use a UML2 component diagram. (60J)
In a large distributed software environment you will likely have a number of components that need to communicate. You should be able to draw these up on boundaries to meet your functional requirements and manpower. You will want some of the communication between applications to be fairly generic. Other communications are bespoke. Where generic interfaces exist, they should be identified before proceeding any further. (5ZS)
Each interface you identify (generic or bespoke) will undergo a RESTful design process. From your specification of the functions of the interface we identify the urls, hyperlinks, methods, and content schemas required to proceed. (5ZT)
Resource (60K)
Once you have nailed down what your interface is supposed to do, it is time to populate the interface with resources. There are a number of aspects to this that reflect the kinds of design you might do if you were developing a web-site for human visitors. (60L)
Step 1: Draw up your resources (5ZU)
Again, I like to use UML as the basis for my diagramming technique. Object-Orientation and REST are closely related in the way they demarcate application state. They mainly differ in the definition of interfaces. (60M)
Think of every atomic operation you need to perform across the interface. You will need a resource that represents the state you wish to transfer during that operation. If you want to be able to turn a light switch off or on, you will need a resource that represents the state of your light switch. If you want to be able to query the balance of your savings account, you will need a resource that contains that information. To play a video you will need resources that represent things like the current selected file, the play rate (fast forward, play, rewind), and the current position in the file. (60N)
Figure out the kinds of resources you need, and draw up the URLs you will give them. Identification and demarcation is the start of the process. (5ZV)
Step 2: Figure out your methods (5ZW)
Each resource will support a number of methods. You should already be able to conceptualise what a PUT or GET request will do to each resource. Some resources will also support POST and some DELETE. Rework your resource list as you find you need to do new atomic operations that require additional resources. (5ZX)
Step 3: Draw your hyperlinks (600)
Some resources will be considered origin resources. These are the ones that are configured into applications as starting points, or discovered by some external means. This might include a kind of "application front page", or a home resource for a particular user. Draw arrows into these resources. (601)
Now, draw additional arrows from these starting points outwards until all resources are accessible from at least one origin resource. Try to keep the number of steps low but relevant, and introduce "form" resources if you need to provide easier stepping-off points to obscure or dynamic resources. Some hyperlinks you get for free, such as the link between a factory resource and the resource created when a client POSTs to the factory. Others you will have to add to the content of resources you have identified. (602)
Rework the earlier steps until everything fits together. (603)
Step 4: Develop your content schemas (5ZY)
Now that you have a clear picture of the state being demarcated by your resources and the hyperlinks you need between them, it is time to formally deduce your content schema. This schema is simply the information you need to transfer in GET, PUT, and POST operations. In Object-Oriented terms this might be the member variables of each resource, however remember that we are defining the schema at an abstract level. Any particular resource will be implemented as the developer sees fit. (60O)
Fill out the attributes section of each resource with the state you will transfer. If your data is only semi-structured, draw a notional XML file containing data of appropriate types. Remember to include the hyperlinks you have drawn into this schema. Again, rework the earlier steps until this makes sense. (5ZZ)
Step 5: Rationalise your content schemas (604)
Look for opportunities to replace one content schema with another. The fewer schemas you have, the better. (605)
When content schemas overlap, consider merging them into a larger common schema. Each resource can use a subset of the larger schema. (606)
When you are satisfied that you have as few content types as possible you can move on to choosing appropriate content formats. (607)
Step 6: Choose formats for your schemas (608)
Format selection is one of the trickiest areas in REST Design. You can pretty much take all other aspects on in isolation, without engaging a larger community. If this is a low-value internal interface you can do the same for this step. Just define a new XML file format or maybe RDF schema and be done with it. If this is a valuable interface, however, you need to begin your research. Look for existing formats in the wild that meet your own schema needs. Use any exact matches. (609)
Look for opportunities to minimally-extend an existing format to meet your special needs, especially with tagging. You may even find that your special needs are not all that special or not necessary. (60A)
Look for mere inspiration from wild formats. Try to stay consistent with existing nomenclature and semantics. (60B)
Look at WhichContentType for additional guidance. (60C)
Summary (60D)
After working through the list of resources, the action of methods on each resource, the hyperlinks between resources, the content schema, and finally the content encoding, you can be sure that you are being as RESTful as you can be. Your software will exhibit the benefits of REST, and the wilder your content types the more network effects you will get from your choices. (60E)