Trends?

XML vs. JSON

Rest vs SOA etc.

However

Your customers, their environment, etc.
vs. global trends.

Rest best practices

continues from yesterday

Resources are nouns, use plurals only to keep it simple.

Rest best practices (continues from yesterday)

Rest best practices

HTTP Return codes

See, e.g., http://www.restapitutorial.com/httpstatuscodes.html

Rest best practices

You can use sub-resources for relations

        GET /books/42/authors/
        GET /authors/
        

Rest best practices

HTTP headers communicating serialization format

• Content-Type defines the request format.
• Accept defines a list of acceptable response formats.

Rest best practices

Authentication and authorization are different. Remember to do both.

There are many other good practices related to designing REST APIs. Some bad practices are also listed, e.g., https://jacobian.org/writing/rest-worst-practices/

Is there anything like WSDL but for REST

Or do I need such?

Web Application Description Language (WADL)

• An XML-based language
• Assumes HTTP
• Uses hyperlinks for linking resources
• Development both language and platform neutral
• Aligned with REST terminology

WADL elements

• Set of resources: Analogous to a site map showing the resources on offer.
• Relationships between resources: Describing the links between resources, both referential and causal.
• Methods that can be applied to each resource: The HTTP methods that can be applied to each resource, the expected inputs and outputs and their supported formats.
• Resource representation formats: The supported MIME types and data schemas in use

WADL in Real

Yahoo has a nice demo: https://developer.yahoo.com/blogs/ydn/check-wadl-7130.html

WADL example

<application xmlns="http://wadl.dev.java.net/2009/02" 
       xmlns:ns="http://superbooks">
 <grammars>
   ...
 </grammars>
 <resources base="http://localhost:8080/">
   ...
   <resource path="/books">
      <resource path="/bookstore/{id}">
        <param name="id" style="template"/>
        <method name="GET">
          <response>
           <representation mediaType="application/xml" element="ns:thebook"/>
          </response>
        </method>
      </resource>
   </resource>
 </resources>  
</application>
        

...WADL example

<grammars>
  <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" 
        xmlns:tns="http://superbooks" attributeFormDefault="unqualified" elementFormDefault="unqualified" 
        targetNamespace="http://superbooks">
    <xs:element name="thebook" type="tns:book"/>
    <xs:complexType name="book">
        <xs:sequence>
            <xs:element minOccurs="0" ref="tns:thechapter"/>
            <xs:element name="id" type="xs:int"/>
        </xs:sequence>
    </xs:complexType>
  </xs:schema>
 </grammars>
     

WADL Tools Support etc

• GlassFish – Sun Java EE 7 Application Server: https://glassfish.java.net/ Support for RESTful Web Services and automatic generation of WADL files from Java code WADL2JAVA https://wadl.java.net/wadl2java.html
• Web Application Description Language (WADL) spec., W3C http://www.w3.org/Submission/wadl/

However, WADL is still not widely adopted.

Thank you