From BC$ MobileTV Wiki
Jump to: navigation, search
RESTful Web Services

REpresentational State Transfer (also refered to as RESTful Web Services; commonly abbreviated REST) is a style of software architecture for distributed hypermedia systems such as the World Wide Web. The terms “representational state transfer” and “REST” were introduced in 2000 in the doctoral dissertation of Roy Fielding [1], one of the principal authors of the Hypertext Transfer Protocol specification. The terms have since come into widespread use in the networking community.[2]

When REST works best

RESTful Customer & Order resources example

It's been offered by Web Service researchers that we consider the best use-cases for REST as it may not be optimal for all data sharing, exposing and integration needs. At the same time, with its robustness and scalability limited only by the already flexible HTTP protocol it was built on, it can be fitted to satisfy most needs (though some situations may be incredibly intuitive while others may be painful, in particular SOAP infrastructure migration or certain server-side automation tasks, and high-level security or service-level authentication and authorization).

REST data (artifacts) should be living documents, like Wikipedia, rather than static editions. But like Wikipedia, they need to be "curated". Or if you prefer a different metaphor, think of them as parts of an "insight engine" for driving your business, which collectively need to be lubricated and maintained to run your business at peak performance. Based on recent assignments, I'm convinced there's a 20-30% time-to-market advantage associated with having these things up to snuff.

RESTlet founder Jérôme Louvel poses the following question you should also ask yourself, before choosing REST: "Do you want to embrace the architecture of the Web and benefit from its simplicity and scalability?" Then in that case (which sounds like most) REST is probably a good fit for you.

"To this end, what's most important to creation of a truly RESTful Web Service is having:

  1. a map that shows where all the data lives,
  2. a dictionary that explains what a piece of data (or parameter) means,
  3. a directory that explains how to get to the data,
  4. a guide that describes how routine analytics get done and associated decisions get made, and
  5. a library (searchable at minimum, if not indexed) that stores all of the individual bits of research (again: queries, regressions, tests, benchmarks) and conclusions you've reached in the past."



Richardson maturity model - how RESTful are your WebServices?

[5] [6] [7]



Hypertext As The Engine Of Application State (HATEOAS) means that the hypertext response returned by a RESTful service/server should be used to find one's way through the application/service's RESTful API. The service navigation or "operation discovery" is provided by <link> elements and named rel attributes specifying what "operation" or "calls" are valid within a specific path. It is said by REST purists that HATEOAS is the "most RESTful option", when it comes to architecting your REST API.

[8] [9] [10] [11] [12] [13] [14] [15] [16]


Siren is a hypermedia specification for representing entities, commonly used in combination with HATEOS (although admittedly more commonly you see custom XML/JSON specs used with HATEOAS, and, Siren could be used on its own as well in more of a POX/POJ manner).



Open Data protocol for REST APIs (commonly abbreviated as OData) is an "open protocol to allow the creation and consumption of queryable and interoperable RESTful APIs in a simple and standard way", it has formats/versions that are compatible with either JSON or Atom/XML. OData aims to provide focus on your business logic while building RESTful APIs without having to worry about the various approaches to defining request & response headers, status codes, HTTP methods, URL conventions, media types, payload formats, query options, and other similar Web Service fundamentals, just to publish an API. By using OData this will be defined for you and tools are provided to help bind/publish your API in the correct format.



Web Application Description Language (WADL) is a port of WSDL for describing RESTful API endpoints.


Restful Api Markup Language (RAML) is a machine-readable API design standard that is actually human-friendly. It is based on the YAML spec. RAML has mechanisms for the definition of HTTP-based APIs' paths, data types, sample requests, access security, creating client/server source code, and comprehensively documenting the APIs for users in a generated HTML page that is easy to read. The "R" in RAML indiicates that it is ideal for APIs which embody principles of Representational State Transfer (REST).


OpenAPI (Swagger 3.0+) logo

The OpenAPI Specification (commonly abbreviated as OAS) is an initiative to encourage public access (where possible legally/financially) and in the very least consistent documentation, accessibility and reliability for APIs. It makes use of the Swagger 2.0 specification to define a standard, language-agnostic interface to REST APIs which allows both humans and computers to discover and understand the capabilities of a specific Web Service without requiring access to source code, design documentation, or the carrying out of painstaking network-traffic inspection throughout regular usage of the API in their supported client (i.e. Wireshark while using a Desktop app, LiveHTTP Headers when accessing a WebApp, etc). When properly defined, a client/consumer can understand and interact with a remote service/device with a minimal amount of implementation logic.

Those behind OpenAPI believe that an "open description format for API services that is vendor neutral, portable and open is critical to accelerating the vision of a truly connected world".

The following image compares Swagger 2.0 spec (later referred to as OpenAPIv2) against the OpenAPIv3 spec which has made some minor structural changes to the base YAML & JSON schema descriptor formats:

Swagger (OpenAPIv2) to OpenAPIv3

[29] [30] [31] [32] [33] [34] [35]

[44] [45] [46] [47] [48] [49] [50] [51] [52] [53] [54] [55] [56] [57] [58] [59] [60]


Swagger is a set of tools enabling simple yet powerful representation of your RESTful API via the OpenAPI spec. With the largest ecosystem of API tooling on the planet, Swagger is used by developers in almost every modern programming language and deployment environment. With a Swagger-enabled API, you get interactive documentation, client SDK generation, discoverability, instant testability and more.

In 2015, Swagger 2.0 was donated to the OpenAPI initiative as an open source standard by SmartBear (creator of SoapUI and many other industry-leading Testing tools). Originally intended as a cleaner alternative to the other SOAP "WSDL-inspired schema formats" for describing RESTful APIs that were emerging in the 2000s-2010s such as WADL & RAML, the humble "Swagger API spec" has come a long way since it was used privately by Reverb (formerly known as "Wordnik") before its acquisition by SmartBear. Both the Swagger 2.x and more recent OpenAPI 3.x versions are now used by many of the top technology companies and Swagger tools were downloaded over 15000 times per day as of 2018.[61]

[62] [63] [64] [65] [66] [67] [68]/ [69] [70] [71]

[72] [73] [74] [75] [76] [77] [78] [79] [80] [81] [82] [83] [84] [85] [86] [87] [88] [89] [90] [91] [92] [93] [94] [95] [96] [97] [98] [99] [100] [101] [102] [103] [104] [105] [106] [107] [108] [109] [110]




RESTlet is a JAVA library for implementing the REST protocol. It provides the following features:

  • Core REST concepts have equivalent Java classes (UniformInterface, Resource, Representation, Connector for example).
  • Suitable for both client-side and server-side web applications. The innovation is that that it uses the same API, reducing the learning curve and the software footprint.
  • Restlet-GWT module available, letting you leverage the Restlet API from within any Web browser, without plugins.
  • Concept of "URIs as UI" supported based on the URI Templates standard. This results in a very flexible yet simple routing with automatic extraction of URI variables into request attributes.
  • Tunneling service lets browsers issue any HTTP method (PUT, DELETE, MOVE, etc.) through a simple HTTP POST. This service is transparent for Restlet applications.
  • Ready for the Semantic Web (Web 3.0), with built-in RDF supports being added to Restlet 1.2.


RESTEasy is a JBoss project that provides various frameworks to help you build RESTful Web Services and RESTful Java applications.

CXF and Spring




1060® NetKernel™ provides a development and computing environment that is simple in concept and far-reaching in implication. The NetKernel open source community is focused on learning how to leverage and extend the technology to a wide range of fields and applications.



Google REST AJAX API for "Transformers Movie" (defaults to JSON)

(XML and SOAP return formats no longer supported by Google Search API)


Yahoo! Web Search for "Transformers Movie"

Defaults to XML return type, for JSON append &output=json


[115] [116] [117]


External Links


  1. “Architectural Styles and the Design of Network-based Software Architectures”: Dissertation for Doctor of Philosophy, by Roy Thomas Fielding
  2. wikipedia:REST
  3. Pragmalytics, Part II:
  4. Roy Fielding's Thesis - Architectural Styles and the Design of Network-based Software Architectures (see Chapter 5 on REST):
  5. Richardson Maturity Model:
  6. Know how RESTful your API is -- An Overview of the Richardson Maturity Model:
  7. What is the Richardson Maturity Model?:
  8. wikipedia: HATEOAS
  9. REST HATEOAS - How does the client know link semantics?:
  10. REST, Hypermedia & HATEOAS:
  11. HATEOAS and the PayPal REST Payment API:
  12. On-Demand Webinar -- Making Sense of Hypermedia APIs - Hype or Reality:
  13. Why I Hate HATEOAS:
  14. Hypermedia APIs (using xHTML parser & <link rel="CONTEXT" />):
  15. Introduction to Hypermedia REST APIs (HATEOAS):
  16. HATEOAS without links (possible but non-standard):
  17. OData icon usage:
  18. Python CLI OData Validator:
  19. New version of OData Validator:
  20. OData Validator (SLIDES):
  21. Testing and Consuming OData Services using Fiddler, LinqPad, Excel and SharePoint:
  22. Understand OData in 6 steps:
  23. A RAML / APIHub Plugin for SoapUI:
  24. wikipedia: Open API
  25. wikipedia: List of open APIs
  26. Planning Your API Strategy for 2018 -- Tools and Resources to Set Your Team Up for Success:
  27. OpenAPI Generator: | SRC
  28. The OpenAPI 3.0 GUI:
  29. Tutorial - Converting your Swagger 2.0 API Definition to OpenAPI 3.0:
  30. What Is the Difference Between Swagger and OpenAPI?:
  31. Convert Swagger 2.0 to OpenAPI 3.0:
  32. Migrating to OpenAPI 3.0 -- How to Convert (migrate) Your Existing APIs with Swagger Tools:
  33. How to convert OpenAPI 2.0 to OpenAPI 3.0?:
  34. Migration from Swagger 2 to OpenAPI 3:
  35. Convert Swagger to OpenAPI using "swagger2openapi" playground: (use command swagger2openapi --yaml --outfile ALC-openapi.json ALC-openapi.yaml)
  36. Add Swagger/OpenAPI to Your Existing APIs: How to Automate a "Code First" Approach to OAS at Scale:
  37. Annotation Libraries for Generating OAS (And Other FAQs from Swagger Users):
  38. Swagger Codegen (with maven plugin) for OpenAPI 3.0:
  39. Tutorial -- Coding a Swagger CodeGen Project:
  40. Swagger codegen tutorial example:
  41. Interactive API documentation using Swagger UI deployed with Terraform:
  42. SwaggerUI and auto-generating API docs from PHP based Application endpoints:
  43. Looking to Create OpenAPI 3.0 For Your API? Swagger Inspector Has Your Back:
  44. Documenting a Spring REST API Using OpenAPI 3.0:
  45. Postman Supports OpenAPI 3.0:
  46. Describing Request Body:
  47. Quick manual way to create an OpenAPI spec from a GET API Request:
  48. Adopting a Design-First Approach with OAS 3.0 & Swagger: (and how to annotate/document legacy APIs)
  49. .NET Core with Swagger and C# Client: | DOCS | SRC
  50. Automatically Generating your API Client with Swagger and Swagger Codegen, by Jesse Collis:
  51. Spotting mismatches between your spec and your REST-API with hikaku:
  52. Swagger/OpenAPI @ApiParam vs @ApiModelProperty:
  53. Doing More With Springdoc-OpenAPI: | SRC
  54. Postman Joins the OpenAPI Initiative:
  55. API Security -- Issue #88 - JWT pentesting, API discovery, the present and future of OpenAPI:
  56. API Scanning with Burp Suite:
  57. Creating High Quality OpenAPI spec (OAS) Definitions with .Net Core
  58. What’s New in OpenAPI 3.1 - JSON Schema & WebHooks:
  59. Analyzing Trends Across 200,000 OpenAPI Files:
  60. Creating (i.e. Reverse Engineering) an OpenAPI spec from application HTTP Traffic:
  61. Introducing the Open API Initiative!:
  62. Visual OpenAPI (Swagger-compatible) API builder:
  63. Chrome extension - SwaggerUI preview:
  64. Swagger + SoapUI = true: (true API testing/integration ease)
  65. Import swagger definition to SoapUI free?:
  66. (SOAP UI) REST Discovery - API with internal browser: (manually record your Swagger API sample requests to create SOAP UI re-runnable tests)
  67. Ready! API Plugin for importing Swagger definitions as REST Services:
  68. Swagger OSS Tools & Integrations:
  69. Swagger - DIFF: (Utility for comparing two Swagger specifications)
  70. Introducing Swagger Brake:
  71. Integrating Swagger Brake into Maven/Gradle projects:
  72. SwaggerHub:
  73. SwaggerHub -- Registry API - Integration:
  74. Integrating with the SwaggerHub API:
  75. Converting a Swagger YAML file to JSON from the command line:
  76. SwaggerHub - API Auto Mocking Integration: (only available on SwaggerHub)
  77. Swagger 101 -- Writing Swagger definitions:
  78. Swagger -- Documenting Existing APIs (and their request/response formats):
  79. Introducing Projects -- A Better Way to Organize Your APIs in SwaggerHub:
  80. A Visual Guide to What's New in Swagger 3.0:
  81. OpenAPI / Swagger Resource List for API Developers:
  82. Swagger-Core Annotations:
  83. Eclipse Plugin -- KaiZen-OpenAPI-Editor:
  84. Swagger markup in a Servlet (EXAMPLE):
  85. How to integrate Swagger with Pure Servlet?:
  86. Swagger Documentation for Servlet:
  87. Generating Rest API documentation using Swagger or any other tool:
  88. How to create Swagger docs (manual example, using SwaggerUI statically):
  89. Swagger tutorial -- How to add Swagger OpenAPI to your REST API documentation:
  90. Generate client stubs & document your REST-API using Swagger & Spring:
  91. Simplified Spring Swagger project example: (SpringFox lib)
  92. How to configure Swagger to generate Restful API Doc for your Spring Boot Web Application:
  93. How to document your JAX-RS API using Swagger, WAS Liberty Profile and Bluemix?:
  94. RESTful API Documentation Using Swagger and Spring MVC:
  95. Usage of Swagger 2.0 in Spring Boot Applications to document APIs:
  96. Can Swagger be used for SOAP?:
  97. REST enable your SOAP services (and document it with Swagger/OpenAPI) using DreamFactory:
  98. How to integrate Swagger with Maven + Java + Jersey +Tomcat:
  99. Swagger 2.0 - Maven plugin: (JAX-RS & SpringMVC supported maven build plugin, helps you generate Swagger JSON and API document in build phase)
  100. Swagger 2.0 - Maven plugin example: (example of using swagger-maven-plugin)
  101. Adding Swagger to Spring Boot:
  102. Java/Spring -- How to Generate an Entire Swagger Documented CRUD REST API With Speedment:
  103. Javalin - Documenting endpoints with OpenAPI 3:
  104. Awesome APIs with Kotlin, Spring 5 and Swagger:
  105. OpenAPI generator: | DOCS | Config Options for kotlin-spring
  106. OpenAPI generation for Kotlin in the Ktor plugin and website:
  107. Swagger for Kotlin:
  108. Simplifying API Pentesting With Swagger import files in "Burp Suite":
  109. How to Turn Off Swagger-ui in Production:
  110. OpenAPI Specification 3.1.0 now available: (JSON Schema, a new top-level element for describing Webhooks, support for identifying API licenses using SPDX identifier; PathItems object now optional, simplifying "reusable component" library creation)
  111. Getting Started with REST Testing in SoapUI:
  112. Example REST Test in SoapUI :
  113. Google Chrome - 3rd party Advanced Rest Client (ARC) test tool:
  114. RECESS former official website: (OFFLINE)
  115. Michal’s PI tips - Exchange Rates from an XML file on a web page – REST, AXIS: | DEMO (lightweight replacement for old WebserviceX CurrencyConverter)
  116. Fixer: ("EURO" as default base RESTful currency exchange rates)
  117. OpenExchangeRates: | DOCS ("USD" as default base)
  118. Do you really need jQuery:
  119. jQuery - Shorthand AJAX methods:
  120. Calling REST API in Java: (Omniture API example)

See Also

API | Web Services | SOAP | SOA | Security | Optimization