GET
and DELETE
operation to occur only at the URI
https://test.api.openstack.com/path/to/my/resource
.
This can be represented in a WADL in the following
manner: <resource>
element. While
the approach would work well in cases where the
API has a complex structure with many resources,
it's overkill for this example. Instead, we can
represent the API like this: <resource>
element
covers multiple segments in the path all at once,
in this case path/to/my/resource
.
Given the sparse API, this is far more convenient.
The WADL need not be entirely written in the form
illustrated in <resource>
elements, one
for path/to/my
and another for
resource
. The ability to intermix
flat and tree forms, allows the WADL author the
flexibility to start with a simple API description
and expand on it as the API grows in complexity.
<method>
,
<representation>
, and
<param>
elements can be
specified separately from individual resources and
therefore can be shared between them. For example
suppose that you have two resources
widgets
and gadgets
both of these resources contain a method to access
metadata. You can repeat the method definition in
both resources as illustrated in id
and the hash (#) is used to
denote the internal link. It's possible that
multiple related methods can be shared between
resources. One can express multiple methods
together, as in resource_type
. A
resource_type
contains common
behavior that can be shared between multiple
resources. This is illustrated in resource_type
s may
capture many different methods. They may also
introduce common sub-resources as illustrated in
<method>
,
<representation>
,
<param>
, and
<resource_type>
elements
need not appear in the same WADL, they may be
linked in from an external WADL as illustrated
below. resource_type
s may be associated
with a single resource. <doc>
element. A simple
illustration of this is shown in the example
below. xml:lang
attribute, multiple
<doc>
elements can be used
each in a different language to aid in the
internationalization of the WADL. The
title
element can be used to give
an overview of the documentation text. <grammars>
element that allows the association of grammars
such as XML Schema with a REST API. Grammars may
be included by means of the
<include>
element as
illustrated in Progress
UUID
path/to/my/resource/3bba8e68-8af5-11e1-ac65-17a552dd2535
and path/to/98
are valid according to
the WADL, but URI paths such as
path/to/my/resource/xyz
and
path/to/101
are not. plain
parameters. This is
illustrated in method in versionDetails
method should
contain an XML payload that validates against the
element defined by the QName
common:version
. Additionally, we
make an assertion that at the XPath
/common:version/atom:link[@rel='self']/@href
there should be a value that validates against the
type xsd:anyURI
. Furthermore, this
URI should provide a link to a resource with a
resource_type
of
VersionDetails
. $['total_size']
,
$['start']
, and
$['entries']
. Additionally the
fields at $['resource_type_link']
,
$['next_collection_link']
,
$['prev_collection_link']
, and
$['entries'][*]['self_link']
should contain links to other resources. representation
without having to
rely directly on JSON schema. wadl:resources
element
wraps one or more resources, as it would
in a normal wadl. wadl:resource
element
wraps one or more methods and defines the
location of the wadl and the
id
of the resource for
the methods. wadl:method
element
points to a method defined in the WADL.
Each method becomes a section
in the resulting DocBook. All of the
methods with a common DocBook
section
ancestor become
section
s within that
section
. Alternatively,
you can omit the wadl:method
and the system will create sections for
all of the methods that are children of
the resource in the target wadl. wadl:resource
and
wadl:method
(s) in the DocBook
document directly. tenantId
parameter are
implied simply because of the URI the method
is associated with. xsdxt:code
extension to associate an example document
with the API response. method
s and
resource_type
s are resolved. Further
processing is therefore greatly simplified. We have
made this tool available as open source software. resource_types
or
refer to a method in an external WADL,
SoapUI cannot load the WADL and throws and
exception. pathformat:
rax:id
attributes have been added to
preserve the original ids that could not be duplicated
in the normalized wadl without making the wadl
invalid. These are required for down-stream processing
when we generate documentation from the normalized
wadl. vc:minVersion
and
vc:maxVersion
attributes. resource_type
elements from the
normalized wadls. In some cases, it is useful to
preserve these element, but they can cause problems
for certain tools. Therefore a parameter is provided
filter out the resource_types
. Input | States Traveled | Result |
GET /path/to/record/2001-01-02 | S0, d18e4, d18e5, d18e6, d18e7, d18e9, SA | 200 Okay |
GET /my/path/ | S0, d30U, d30U, d30U | 404 Not Found |
PUT /path/to/record/2001-01-02 | S0, d18e4, d18e5, d18e6, d18e7, d30M | 405 Bad Method |