nicholasarodriguez.files.wordpress.com · web view2020. 9. 10. · alternatively, the http...

Technology PracticeRESTful Web Services Standards

Practice Number: R113140Effective Date: 01/14/2019TSS Section: MiddlewareProduct Name: NoneCompetency Area: RESTful Web ServicesAudience: Interface Designers and Architects

Contact InformationResponsible Owner Name(1): Compliance with this practice is the responsibility of

every employee.Responsible Supervisor Name(2): Employees with supervisory responsibility are

responsible for ensuring that all of their subordinates know, understand, and comply with this practice.

Technology Practice R11340 Technology Architecture Board

RESTful Web Services StandardsJanuary 14, 2019

of 26



Table of Contents1. Definitions.................................................................................................6

1.1 API Name....................................................................................................................6

1.2 HTTP...........................................................................................................................6

1.3 JSON...........................................................................................................................6

1.4 Major Version.............................................................................................................6

1.5 Minor Version.............................................................................................................6

1.6 Operation...................................................................................................................6

1.7 Representational State Transfer (REST).....................................................................6

1.8 RESTful Web Services.................................................................................................6

2. Practice Description...................................................................................72.1 Overview Statement...................................................................................................7

2.2 Issue/Problem.............................................................................................................7

3. Context.....................................................................................................7

4. Rationale...................................................................................................7

5. Implementation Requirements....................................................................85.1 Requirements for Existing Applications......................................................................8

5.2 Industry Standards.....................................................................................................8

5.3 Architecture................................................................................................................85.3.1 Use of Java Based Implementation Standard (JAX-RS)..........................................85.3.2 Messaging Transport............................................................................................85.3.3 Application Exchange of Libraries (e.g., Libraries, JAR files).................................95.3.4 Message Sizes......................................................................................................95.3.5 Service Scope and Granularity.............................................................................95.3.6 Message Payload Definition................................................................................10

5.4 Security....................................................................................................................10

5.5 Middleware and Data Standards...............................................................................115.5.1 General Naming Standards.................................................................................115.5.2 Schema Validation..............................................................................................115.5.3 XML Standards...................................................................................................115.5.4 JSON Date and Time Representation..................................................................125.5.5 RESTful Web Services.........................................................................................12

5.5.5.1 Resource Naming.........................................................................................125.5.5.2 Versioning....................................................................................................135.5.5.3 Methods.......................................................................................................15

of 26



5.5.5.4 Content........................................................................................................165.5.5.5 Callbacks......................................................................................................205.5.5.6 Internationalization......................................................................................205.5.5.7 State............................................................................................................215.5.5.8 Caching........................................................................................................215.5.5.9 Errors...........................................................................................................225.5.5.10 Response Status Codes...............................................................................235.5.5.11 URL Requirements......................................................................................285.5.5.12 HTTP Extended Headers..............................................................................285.5.5.13 Returned URLs............................................................................................31

5.6 Interface Specification Requirements.......................................................................32

5.7 Patterns and Anti-Patterns.......................................................................................335.7.1 Commands.........................................................................................................335.7.2 Concurrency Control...........................................................................................345.7.3 Large Message Payloads....................................................................................34

5.7.3.1 Pagination....................................................................................................345.7.3.2 Streaming Content.......................................................................................36

5.7.4 Partial Resource Updates...................................................................................375.7.5 Processes and Transactions................................................................................375.7.6 Remote Procedure Call (RPC).............................................................................385.7.7 Restricting Output..............................................................................................405.7.8 Sub Resources....................................................................................................42

6. Consequences: Pros, Cons, Limits............................................................446.1 Pros..........................................................................................................................44

6.2 Cons.........................................................................................................................44

6.3 Limits.......................................................................................................................44

7. Related Patterns/References/Aids.............................................................447.1 Related Patterns.......................................................................................................44

7.2 References...............................................................................................................45

7.3 Aids..........................................................................................................................45

8. Governance.............................................................................................458.1 Governance..............................................................................................................45

9. Exceptions...............................................................................................45

10. Appendices..............................................................................................4510.1 Appendix A Change History...................................................................................45

of 26



1. Definitions

1.1 API NameA name used to group a set of related resources.

1.2 HTTPHypertext Transfer Protocol (HTTP/1.1) as defined by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, and RFC 7235

1.3 JSONJSON or JavaScript Object Notation is a lightweight text-based open standard designed for human-readable data interchange. It is derived from the JavaScript scripting language for representing simple data structures and associative arrays, called objects. Despite its relationship to JavaScript, it is language-independent, with parsers available for most languages.

JSON is specified in ECMA-404. The official Internet media type for JSON is application/json. The JSON filename extension is .json.

The JSON format is often used for serializing and transmitting structured data over a network connection. It is primarily used to transmit data between a server and web application, serving as an alternative to XML.

1.4 Major VersionWhen a new version of an API is created, it is defined to be a major version if the change to the interface breaks existing clients using the previous API version.

1.5 Minor VersionWhen a new version of an API is created, it is defined to be a minor version if the change to the interface does not break clients using the previous API version.

1.6 OperationA unique HTTP method and resource name in an API. For example, in a Video Management API, “PUT /videos” and “DELETE /videos” are two separate operations.

1.7 Representational State Transfer (REST)Representational State Transfer (REST) is a software architecture style for distributed hypermedia systems like the World Wide Web. The term originated in a 2000 doctoral dissertation by Roy Fielding entitled, “Architectural Styles and the Design of Network- based Software Architectures.”

of 26

http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm

http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm

http://www.ecma-international.org/publications/standards/Ecma-404.htm

https://www.rfc-editor.org/info/rfc7235









1.8 RESTful Web ServicesRESTful Web Services are Web Services that generally conform to the REST architecture style in that they:

Are resource based; resources are described by a hierarchical URI structure Have a uniform interface consisting of the HTTP verbs Use the HTTP transport Are stateless

2. Practice Description2.1 Overview StatementThe practices listed in Section 7 apply to new and modified RESTful Web Services. Adherence to the requirements in this document is required upon ratification.

2.2 Issue/ProblemThis practice defines usage requirements and recommendations for a class of middleware called RESTful Web Services.

It is expected the requirements and recommendations in this document will evolve with industry tools, industry standards, and user experience.

This practice assumes knowledge of RESTful Web Services and is not an educational document

3. ContextThis practice applies to all inter-application RESTful Web Services solutions performed by or on behalf of AT&T that offer RESTful Web Services interfaces.

COTS products and external partners that require fixed RESTful Web Services or specifications are exempt from these requirements but RESTful APIs provided by COTS products must conform to the definition of RESTful Web Services.

RESTful Web Services exposed to external entities, such as customers or business partners, must conform to the requirements of this practice. But these implementations may be subject to more restrictive requirements, especially security, privacy, and regulatory requirements, than those specified by this practice (e.g., North Bound APIs offered via the AT&T Developer Program, which are governed by the North Bound API Standards).

of 26

http://tss.att.com/show_document.cfm?documentid=379



4. RationaleRESTful Web Services is inherently open to interpretation due to the lack of industry standards. This Practice is necessary to define what minimally constitutes RESTful Web Services in AT&T and to provide design and implementation requirements and recommendations.

5. Implementation Requirements5.1 Requirements for Existing Applications

Existing services or platforms that do not conform to the requirements specified in this document are grandfathered. They should be brought into compliance when they are modified and where it makes business sense to do so.

The following material is applicable to New Applications 5.2 Industry Standards

Some APIs may be required to conform to industry standards such as OMA OneAPI or WAC.Requirements: APIs that are required to conform to a specific industry standard shall conform to the requirements of this document except where they conflict with the industry standard that they realize. Where there is disagreement, the industry standard shall prevail.

5.3 Architecture5.3.1 Use of Java Based Implementation Standard (JAX-RS)

The Java community defined a standard for the implementation of RESTful Web Services, JSR 339: JAX-RS 2.0: The Java API for RESTful Web Services. AT&T’s Java-based RESTful service implementations are expected to use JAX-RS in lieu of proprietary frameworks.Recommendation:

Where the intellectual property is owned by AT&T, Java-based RESTful Web Services should use JAX-RS.

5.3.2 Messaging TransportRESTful Web Services use the HTTP transport at the exclusion of all other transports. Occasionally, claims that RESTful Web Services may use transports other than HTTP are encountered. But such claims are not broadly accepted.RESTful Web Services not only uses HTTP as the message transport, but it uses HTTP as the application protocol; i.e., uses the semantics of the HTTP verbs, response codes, and headers.Requirements:

of 26

http://jcp.org/en/jsr/detail?id=339

http://www.gsma.com/oneapi/

http://www.openmobilealliance.org/API/APIsInventory.aspx



RESTful Web Services must use only HTTP/HTTPS 1.1 as their messaging transport.

5.3.3 Application Exchange of Libraries (e.g., Libraries, JAR files)Some applications assist client applications by providing them with JAR files, libraries, and other runtime components that the client may use to call their services.When runtime components are provided to clients by service providers, the service provider, by default, assumes support responsibility for the client application, an undesirable situation.This may seem insignificant but it becomes significant when the client encounters problems the service provider cannot support in the timeframe required. Furthermore, the introduction of foreign middleware components into a client application can override the native configuration and management infrastructure used by the application, resulting in a “one-off” configuration and management infrastructure for an interface. Requirements:

Service providers must not provide runtime components to client applications that are different MOTS applications than the service provider’s MOTS application. Service providers may provide example source code that illustrates how to use the interface in the context of an interface specification document.

5.3.4 Message SizesThe ability to support large message transfers varies with the hardware/software platforms in use. RESTful Web Services is middleware that is not intended to replace batch file transfer tools (such as Connect:Direct) or ETL (Extract Transform and Load) tools.Run-time memory configuration and/or HTTP transport properties typically limit the maximum message size of a data transfer. Additionally, physical memory and operating system differences affect the ability of servers and clients to support large messages. Recommendations:

Except where streaming is used, message sizes should be less than 500k uncompressed text such as application/xml and application/json. Larger messages are possible depending on the message structure and environment; applications should be wary of larger messages and test them to assure they work for both servers and clients. When message sizes exceed the maximum message size, the service provider assumes the associated risk. It is the service provider’s responsibility to resolve issues encountered with large messages that exceed the recommended message size.

5.3.5 Service Scope and GranularityService scope standards reduce complexity, enhance usability, and promote consistency across the API portfolio. Most services operate on an underlying entity (e.g., an account, order or message) which exists within a hierarchy of entities (e.g.,

of 26



SMS fits within Messaging which fits within Communications). Service scope standards address the granularity of services and the operations they contain.Recommendations:

A RESTful web service shall target less than 25 resources. If more than 25 resources are likely to be implemented over time, then the service shall be redesigned to operate on a smaller entity scope. For example: if a ‘Multimedia’ service could reasonably be expected to support 100 resources, it should be redesigned into several smaller services organized by market segment, product, technology or other entity. What matters is not the number of resources in the initial deployment of the RESTful web service, but rather the likely number of resources that the service will grow to support given the scope of the underlying entity.

5.3.6 Message Payload DefinitionMessage payload definitions have a significant impact on the usability of an API and the ability to detect errors early in the development process. Payload definitions must not obfuscate message content through a lack of strong typing.Requirements:

Message definitions must not use opaque types such as name-value pair arrays, strings that contain multiple elements that must be parsed, and strings that contain XML documents.

5.4 SecurityRequirements: 1. RESTful Web Services implementations must comply with the AT&T Security

Policy and Requirements including authentication, authorization, auditing, and encryption.

2. RESTful Web Services must use Application Authorization Framework (AAF) for authentication and authorization. Special cases are:

Existing CSI services will continue to use Partner Profile Modelled services must use Partner Profile Services that are externally exposed via CSI Gateway must use Partner

Profile

AAF referencesi. Authorization using AAF ii. AAF documentation and associated CADI documentation

3. Except for Northbound APIs, inter-Application interfaces must use the HTTP Basic Authentication Scheme as specified by HTTP for credentials transmission.

4. All APIs must use HTTPS. Note that this does not require client certificates.5. URIs, including query parameters, must not contain data classified as AT&T

Proprietary (Restricted), AT&T Proprietary (Secure Restricted), AT&T Proprietary (Sensitive Personal Information (SPI)), or Information Belonging to a Customer of AT&T. As an alternative to including this data in the URI is to include it in an extended header.

6. ASPR-0206:Pre-Classified Data Elements

of 26

https://attegrc.cso.att.com/attegrc/default.aspx?requestUrl=..%2FGenericContent%2FRecord.aspx%3Fid%3D4116369%26moduleId%3D370

https://attegrc.cso.att.com/attegrc/foundation/Workspace.aspx?workspaceId=-1&requestUrl=..%2FGenericContent%2FRecord.aspx%3Fid%3D4116588%26moduleId%3D370




https://attegrc.cso.att.com/attegrc/default.aspx?requestUrl=..%2FGenericContent%2FRecord.aspx%3Fid%3D4116373%26moduleId%3D370



https://wiki.web.att.com/display/cadi/CADI+Framework

https://wiki.web.att.com/display/aaf

https://wiki.web.att.com/display/ajsc/Authorization+Using+AAF

http://tss.att.com/tssr/product.cfm?pid=7177

http://cso.att.com/ASPR/Library.html

http://cso.att.com/ASPR/Library.html



5.5 Middleware and Data Standards

5.5.1 General Naming StandardsNaming standards reduce complexity, enhance discovery and promote consistency. Requirements: 1. The Corporate Data Naming Standards (CDNS) practice applies. See

http://tss.att.com/document/R002231.pdf2. Use full form American English words, except where an industry standard

abbreviation is used or where appropriate. 3. Use camelCase naming style http://en.wikipedia.org/wiki/Camelcase4. Names shall describe the functional scope of the entities (e.g., resources and data

structures) they represent.5. The functional scope of names shall not exceed the functional scope of the entity

being named. For example, a service that provides SMS messaging operations should not be named ‘messaging’ because the functional scope of ‘messaging’ exceeds that of ‘shortMessageService’. Names that are too broad in scope will impair discovery and increase the likelihood of naming collisions.

6. Abbreviations and acronyms shall be expanded to support understanding and discovery. Example: ‘accountPs’ would cause nearly every reader to wonder what ‘Ps’ meant? It should be written ‘accountProfileService’ instead.

7. Where JSON is used, field and object names shall start with a small letter and shall follow the general naming requirements of this practice.

5.5.2 Schema ValidationXML Schema validation is stringent, not allowing data elements to appear in a document which do not appear in the XML Schema used for validation. This behavior can have negative impacts as it prevents services from adding extra elements to response messages without impacting existing clients. As a result, it is recommended that clients not use XML Schema validation.A JSON Schema and validation exist in draft form. JSON Schema validation is not understood well enough to make usage recommendations.Recommendations:

To minimize the impact of minor version changes, clients should not use XML Schema validation.

5.5.3 XML Standards Requirements: 1. Services that use XML must comply with the AT&T XML Standards.2. XML sent in messages must be described by XML Schema. 3. Request and Response messages that contain XML must contain only one XML

document.

5.5.4 JSON Date and Time RepresentationSome applications are sensitive to precise date and time representation, particularly with respect to time zone.

of 26

http://tss.att.com/document/R031351.pdf

http://json-schema.org/

http://en.wikipedia.org/wiki/Camelcase

http://tss.att.com/document/R002231.pdf



Requirements: 1) Applications that are sensitive to precise date and time representations, including

time zone must represent JSON dates and times in the complete ISO 8601 format as shown below. The time zone should be UTC though time zone offsets are acceptable.Complete date plus hours, minutes, seconds and a decimal fraction of a second YYYY-MM-DDThh:mm:ss.sTZD (e.g., 2014-01-01T23:28:56.782Z)where: YYYY = four-digit year MM = two-digit month (01=January, etc.) DD = two-digit day of month (01 through 31) hh = two digits of hour (00 through 23) (am/pm NOT allowed) mm = two digits of minute (00 through 59) ss = two digits of second (00 through 59) s = one or more digits representing a decimal fraction of a second TZD = time zone designator (Z or +hh:mm or -hh:mm) where Z = UTC

5.5.5 RESTful Web ServicesREST resources are effectively objects referenced by URIs, with support for four HTTP methods (GET, POST, PUT and DELETE). A ‘representation’ is an encoding or formatting of the state of a REST resource. Communication takes place on a call from the client to the server. The client is active and requests a representation from, and/or modifies a resource on, the passive server.

5.5.5.1 Resource NamingREST resources are addressed by a unique URL, subject to the following requirements:

Requirements: 1. Resource URLs shall conform to the following format:

http[s]://serverBaseURL{/routing}* {/APIName}/{version}{/resourcePath}

serverBaseURL Hostname + optional portrouting Zero or more routing path segments for server

routing and proxyingAPIName The name of the API. This is not a resource

component. It a name used to group a set of related resources.

version The version of the API in the format: Major version:

of 26

https://en.wikipedia.org/wiki/ISO_8601



o "v" positive integer (e.g., v1, v3, v10)resourcePath The resource name segments of the resource being

operated on. One or more path segments is required except when the API or version is used for discovery.

Table 1 – Format of REST Resource URL

2. Lower camel case shall be used when multiple words and/or acronyms are concatenated with no intervening delimiters.

3. Resource path segments that represents a collection of resources must be a plural noun

/tenants/{tenantId} – tenants represents a collection of tenants4. Resource path segments that represent a singleton resource may be a singular

noun5. Accesses to a member in a collection must be prefixed by the collection name

/tenants/{tenantId} – {tenantId} represents a tenant in the tenants collection with a particular Id.

5.5.5.2 VersioningREST versioning is achieved by specifying the major version number in the REST URL. A major version is interpreted to mean a separate set of resources from the previous version. Minor versions are backwards compatible and are therefore not identified in the URL.

Requirements: 1. If a change is made to the request/response format which is not backwards

compatible, the major version number shall be incremented.2. The major version shall be communicated in the REST URL as specified in the

previous section.3. Major version deployments shall not require consumers to migrate to the new

version when the new version is deployed unless there is a critical business requirement that requires such a migration. For example, regulatory or security requirements.

4. Deprecated major versions must be supported for at least 12 months after the next major version is deployed unless a shorter time period is negotiated with all clients.

of 26

Messaging Example:

https://messaging.att.com/SmsMessaging/v1.0/messages

[note: the actual message will contain additional resource-specific path info identifying the resource following the

‘SmsMessaging’ resource name]

https://messaging.att.com/SmsMessaging



5. Minor versions shall be backwards compatible under the assumption that clients will ignore unknown elements.

6. To maintain backwards compatibility across minor versions, the following guidelines should be observed for XML and JSON APIs:

a. New input elements and attributes may be added to operations provided they are not required.

b. The data types of input elements and attributes may be versioned by adding elements, attributes, choice, and enumeration values, provided they are not required by the operation and provided the old choices and values continue to be supported.

c. New output elements and attributes may be added to operations though there is a risk of existing client incompatibility if the client uses schema validation, which is not recommended for clients (per Schema Validation Section).

7. When clients can use resource versions other than the current version, the server must handle HTTP verbs executed against prior versions as follows:

a. The server must respond with HTTP status code 405 (Method Not Allowed) when an HTTP verb cannot be executed because the verb is not supported due to incompatible changes by a subsequent version.

b. PUT: Must accept representations compliant with the specification of the version executed.

c. GET: Must return representations compliant with the specification of the version executed.

d. POST and DELETE: Behavior must comply with the specification of the version executed.

e. Representation Persistence: If the persisted representation of a resource was modified between versions, the server must resolve inconsistencies between versions.If a subsequent version added new elements then the server must ensure that operations executed on prior versions set the new elements to an appropriate value and do not inappropriately overwrite existing values.

Example:

Definitions

/subscriber/v1 {productName, subscriberName}

/subscriber/v2 {productName, subscriberName, subscriberId}

If version 1 is supported after the introduction of version 2

Verb

subscriber/v1

GET Must return {productName, subscriberName}

of 26



Must not return subscriberId

PUT Must accept only {productName, subscriberName} Implementation must account for subscriberId in the persistent

store; implementation is domain specific but might consist of retaining the present value or executing an algorithm to set the value

5.5.5.3 MethodsHTTP methods operate on REST resources. Requirements: 1. REST resources may support the HTTP GET, PUT, POST and DELETE methods and

shall support no other methods.2. DELETE shall be used to remove a resource.3. DELETE shall not contain a message payload.4. GET shall be used to retrieve a representation of the state of the resource.

Query parameters shall be used to provide any input parameters necessary to generate the output.

5. GET shall treat REST resources as read only. 6. In cases where the URI could exceed 2048 characters, the API design shall use

POST instead of GET and the query string parameters shall be in the HTTP body. In this case, the POST method shall be read only.

7. PUT shall be used to replace a resource and it may be used to create a resource when the URL of the target resource is used in the request. PUT’s input must be the resource’s full representation, it cannot be a partial representation.

8. POST shall be used to add information to a resource (aka ‘paste after’) or to update one or more subordinates of a specified resource. POST shall also be used to create a subordinate of a specified resource using a server-side algorithm. POST operations are generally non-idempotent meaning the operation cannot be repeated without side effects. For example, a POST operation that results in a charge to a credit card cannot be safely repeated (e.g., in the case of a timeout) without potentially generating multiple charges to the credit card. Note: POST operations can be made idempotent by providing some data in the payload (e.g., a TransactionId) which the service implementation checks for uniqueness.

9. POST shall be used when no other HTTP method seems appropriate.10. GET, PUT and DELETE operations shall be idempotent meaning that multiple

executions of the same operation results in the same resource state as a single execution of that operation.

11. As specified by HTTP (Roy Fielding et al), conditional PUTs may use the IF- MATCH or IF-UNMODIFIED-SINCE HTTP request header fields. Conditional GETs may use the IF-UNMODIFIED-SINCE HTTP request header:

a. A request intended to update a resource (e.g., a PUT) may include an If-Match header to signal the request method must not be applied if the

of 26

https://tools.ietf.org/html/rfc7232#page-13



entity corresponding to the If-Match value is no longer a representation of that resource. This allows the user to indicate they do not wish the request to be acted on if the resource has been changed without their knowledge. Examples:

If-Match: “xyzzy” If-Match: “xyzzy”, “r2d2xxx”, “c3piozzzz” If-Match: *

b. The If-Unmodified-Since request-header is used with a method to make it conditional. If the requested resource has not been modified since the time specified in this field, the server should perform the requested operation as if the If-Unmodified-Since header were not present. If the requested variant has been modified since the specified time, the server must not perform the requested operation, and must return a 412 (Precondition Failed). If the request normally (i.e., without the If-Unmodified-Since header) would result in anything other than a 2xx or 412 status, the If-Unmodified-Since header should be ignored. If the specified date is invalid, the header is ignored. Examples:

If-Unmodified-Since: Sat, 29 Oct 1994 19:43:31 GMT12. If a request is made of a resource using a method that is understood by the

server but not supported by that resource (e.g., PUT on a resource that only supports POST), a HTTP status code 405 (Method Not Allowed) shall be returned. The Allow header shall also be sent in the response with a list of the methods that are supported by the resource.

5.5.5.4 ContentREST message format (aka a REST ‘representation’) is an encoding or formatting of the state of a REST resource. The message format type used in the response message body should generally match the message format type used in the request body.Requirements: 1. Structured, text based representations (excluding streaming (i.e., file transfer)):

a. JSON should be used because it is the increasingly dominant format used by industry

b. Messages containing JSON should specify application/json in the HTTP Content-Type header field

c. XML may be used when there is a strong reason to use XML instead of JSONd. XML must be used in conjunction with XML Schemae. Messages containing XML should specify application/xml in the HTTP Content-

Type header fieldf. JSON and XML should not be supported by the same API. Support for both

increases testing, documentation, and support costsg. Request and response HTTP Content-Type headers for the same operation

must be identical if one exists 2. Structured, text based, streaming (see Streaming Content) representations must

use JSON, XML, or Comma Separate Values (CSV)

of 26

https://tools.ietf.org/html/rfc7231#page-59



a. Messages containing CSV must specify text/csv in the HTTP Content-Type header field

b. Messages containing JSON should specify application/json in the HTTP Content-Type header field

c. Messages containing XML should specify application/xml in the HTTP Content-Type header field

d. Streamed messages in an API should support only one content type due to testing, documentation, and support costs

e. Plain text may, perhaps with a unique delimiter, be used with an exception Example: text/plain; header="present";delimiter="|";charset="utf-8”

3. PDF representations must use HTTP Content-Type application/pdf.4. Structured text representation of empty collections

a. A response that represents a collection must return an empty collection instead of returning a 404 status code to indicate that there are no entities in the collection. The empty collection must be compatible with the response when entities are present. The rationale is that the collection is found, but is empty.

b. A 404 response is appropriate when the response for a single resource (non-collection) is not found, or when the resource specified for the path doesn’t exist.

c. Example 1

of 26



d. Example 2

5. Requests may be submitted in application/x-www-form-urlencoded format, as specified in http://www.w3.org/TR/html401/interact/forms.html). This format can be used with POST requests, supporting the use case of submitting a representation of a data structure directly from HTML forms by a web browser. It can also be used with GET requests to pass parameters. Note: in www-form-urlencoded bodies, there is neither an indication of the XML document declaration

of 26

GET /accounts returns a resource representation that has a field named “links” and a field named “collection”:

When there are accounts to return:{ "links": [ …links… ], "collection: [ { account_1 }, { account_2 }, etc... ]}

When empty:

{ "links": [ …link_values… ], "collection: []}

GET /users returns a raw list representation of a collection of users

When there are users to return:[ { user_1 }, { user_2 }, etc...]

When empty:[]

http://www.w3.org/TR/html401/interact/forms.html



( <?xml version="1.0" encoding="UTF-8" ?>) nor the declaration of namespaces or schemaLocations.

6. Other content formats shall be described by MIME types assigned by IANA (http://www.iana.org/assignments/media-types/).

7. If multiple attachments are to be sent as part of the client request (or callback request from the server to the client’s callback URL), MIME Content-Type multipart/related shall be used

8. In compliance with OMA guidelines, a MIME multipart message shall consist of the following parts:

a. A ‘root’ part expressed in the different possible encoding formats (application/xml, application/json or for requests only: application/x-www-form-urlencoded). The ‘root’ part shall be included as a single form field with a MIME body as follows:

Content-Disposition: form-data; name=”root-fields”Content-Type: <encoding format>…specific fields formatted per the encoding format…

b. If the message contains only one additional part, it shall be included as a single form field with a MIME body as follows:

Content-Disposition: form-data; name=”attachments”Content-Type: <encoding format>…specific multimedia or other content formatted per the encoding format…

c. If the message contains more than one additional part beyond the ‘root’ part, it shall be included as a single form field with a MIME body as follows:

Content-Disposition: form-data; name=”attachments”Content-Type: multipart/mixed…one or more subparts included as follows:…Content-Disposition: attachment; filename=”<name of content>” Content-Type: <encoding format>specific multimedia or other content formatted per the encoding format…

d. For every body part and subpart, other parameters (e.g., Content-Description, Content-Transfer-Encoding) may be included.

e. MMS Example:…Other http headers…Content-Type: multipart/form-data, boundary=asdfa487--asdfa487Content-Disposition: form-data; name=“root-fields”Content-type: application/xml… XML representation of the MMS root fields (e.g., origin, destination addresses, subject, priority, message identifier, etc.)…--asdfa487Content-disposition: form-data; name="attachments"Content-type: multipart/mixed, boundary=BbC04y

of 26

http://member.openmobilealliance.org/ftp/public_documents/arch/ARC-REST/Permanent_documents/OMA-WP-Guidelines_for_REST_API_specifications-20100827-D.zip

http://www.iana.org/assignments/media-types/



--BbC04y Content-disposition: attachment; filename="textBody.txt" Content-Type: text/plain; charset= “UTF-8” Content-Transfer-Encoding: 8-bit ... text of the MMS ... --BbC04y Content-disposition: attachment; filename="file2.gif" Content-type: image/gif Content-Transfer-Encoding: base64 ...contents of file2.gif...

--BbC04y…Other attachments delimited by the boundary string… --BbC04y--

--asdfa487--

5.5.5.5 CallbacksA callback request is made by a client to a server. The client establishes a server (aka a ‘listener’) that listens on a callback URL. When it makes a request, the client provides the callback URL to the server, along with a correlation identifier (aka a correlator). The server can then send information to the client via the callback URL referencing the correlation identifier. The correlation identifier enables the client to distinguish the results of different callback requests using the same callback URL. For the requirements below see section HTTP Extended Headers for definitions of the headers referenced. Requirements: 1. For callback requests, clients shall provide a callback URL in the X-ATT-ReturnURL

header in the request message.2. For callback requests, clients shall provide a correlator in the request message.

The correlator may be a message value, such as order number, or it may be the client provided value in the X-ATT-MessageId.

3. Servers shall issue responses to the callback URL provided by the client in Requirements (1).

5.5.5.6 InternationalizationRequirements: 1. For XML and JSON serialization, UTF-8 encoding shall be used in XML and JSON

requests and responses. For example Content-Type: application/xml; charset=”utf-8”<?xml version="1.0"

encoding="UTF-8"?> Content-Type: application/json;

Content-Transfer-Encoding: 8bit

of 26



<json UTF-8 data>2. For form-urlencoding serialization, only alphanumeric ASCII characters [0-9, a-z,

A-Z] and a limited set of other characters ($-_.+!*'()) may be included directly (see RFC 1738). Other unsafe and reserved characters may be exchanged too but must be escaped (",?, etc.). For example:

Content-Type: application/x-www-form-urlencodedmessage=quedar%EDamos+ma%F1ana&address=621444448

3. For the exchange of binary data, base64 will be taken as Content-Transfer-Encoding.

5.5.5.7 StateThe server does not monitor the state of its clients or maintain state for its clients. Each request to a server is an independent transaction that must contain all information necessary to execute the request.Requirements: 1. REST services shall be stateless. Servers shall not maintain state for clients. State

shall be maintained by clients. 2. Servers shall not issue cookies as they are a receipt for application state.

5.5.5.8 CachingAs REST supports caching, the server can set its responses as cacheable or non-cacheable. If the normal case, where HTTPS is being used however, there are no intermediate elements to do caching.Requirements: 1. The HTTP Expires header may be provided by GET operations to reduce the

number of network round trips from clients re-requesting data that hasn’t changed. The Expires header field gives the date/time after which the response is considered stale. To mark a response as "already expired," the REST server sends an Expires date that is equal to the Date header value. To mark a response as "never expires," an origin server sends an Expires date approximately one year from the time the response is sent. Note: HTTP/1.1 servers should not send Expires dates more than one year in the future. An example Expires header:

Expires: Thu, 01 Dec 1994 16:00:00 GMT2. Alternatively, the HTTP Cache-Control “max-age” directive may be provided by

GET operations instead of the Expires header. Note: unlike the Expires header, most HTTP/1.0 caches will neither recognize nor obey this directive. Where present, the Cache-Control “max-age” directive overrides the Expires directive. When the “max-age” Cache-Control directive is present in a cached response, the response is stale if its current age is greater than the age value given (in seconds) at the time of a new request for that resource. The “max-age” directive on a response implies that the response is cacheable (i.e., "public") unless another, more restrictive cache directive is also present. An example Cache-Control header:

Cache-Control: max-age = 1803. POST requests shall not be cached. The REST service shall set the HTTP CACHE-

CONTROL header field to indicate “no-cache”. This directive requires that all of 26

http://www.ietf.org/rfc/rfc1738.txt



caches between the client and server must not use the response to satisfy a subsequent request without successful revalidation with the REST service. This allows the REST service to prevent caching even by caches that have been configured to return stale responses to client requests. The format of the no-cache header directive is provided below [note: most HTTP/1.0 caches will not recognize or obey this directive]:

Cache-Control: no-cache

5.5.5.9 ErrorsRESTful services generate and send exceptions to clients in response to invocation errors. Exceptions shall conform to the following sample structure:

Requirements: 1. Exceptions shall comply with the HTTP 1.1 specification.2. Minimally, exceptions shall be sent with the HTTP status line, consisting of the

HTTP version, response status code and ‘reason phrase’.3. Exceptions shall use and conform to the requirements specified in the Response

Status Codes section of this document. 4. Where multiple response status codes could be used, the most specific and

descriptive response status code shall be used.5. The content of the exception message text must not reveal the technology used

to implement the service (e.g., stack trace, southbound applications) and, therefore, make the service more vulnerable to attack.

6. The optional error structure shall conform to the following: Field Name Data Type Required? Description

errorId xs:string Yes Unique errorId in the context of an API.

Recommendation: two hyphen-delimited subfields: Domain: identifies the API, application,

service or general category to which the error belongs. Note that the

of 26

http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html



Field Name Data Type Required? Descriptiondomain “ATT” is reserved for common errors to be defined in the future.

Code: provides a unique numeric code within the Domain.

Examples: General-0001, DataDict-0001

message xs:string Yes Message textvariables xs:string

[0..unbounded]No List of zero or more strings that represent

the contents of the variables used by the message text.

errorUrl xs:anyUrl No Hyperlink to more information about the error, including causes and solutions.

5.5.5.10 Response Status CodesHTTP status codes are returned in response to REST operation invocations. The status code is a three-digit number, starting at 100 and up to 599 (although most that range is not used). HTTP groups the status codes together, based on the type of status. The first digit of the status code groups each status type. So, by examining the first digit you can get an idea of the status type and in some cases, you can decide based on that.

Status Code Group

Category Description

1xx Informational This group is for status codes that provide informational statuses.

2xx Successful The request was understood and accepted.3xx Redirection Further action is needed before the request can be

completed.4xx Client Error The request was constructed incorrectly (bad syntax,

wrong permissions, etc.) by the client.5xx Server Error The request was valid, but the server was unable to

fulfill the request.A helpful reference diagram is located here. Note that the requirements in this document prevail where there are differences.

5.5.5.10.1 General Response Status Code Requirements: 1) Where multiple response codes could be used, the most specific and descriptive response

code shall be used. For example if a PUT operation using JSON content type was invoked on a resource that did not support PUT or JSON: 405 Method Not Allowed should be used over 401 Unauthorized or 404 Not Found or 415 Unsupported Media Type or 406 Unacceptable

2) Status codes shall be consistent with HTTP. They follow the format HTTP-Version SP Status-Code SP Reason-Phrase CRLF and are listed on the first line of the response (called the status line), examples:

- HTTP/1.1 200 OK

of 26

https://www.loggly.com/blog/http-status-code-diagram/



- HTTP/1.1 405 Method Not Allowed- HTTP/1.1 500 Internal Server Error

5.5.5.10.2 Success Status Code Requirements: 1. Successful 2XX Response Code Decision Tree

2. Successful GET responses shall return the following codea. 200 (OK): successful response that includes the resource representation

requested.

3. Successful POST responses shall return the following codes:a. 200 (OK): A message body is included in the response and this was not in

response to a resource creation (201).b. 202 (Accepted): The request has been accepted for processing, but the

processing has not been completed. The request might or might not eventually be acted upon, as it might be disallowed when processing takes place it

c. 201 (Created): if a resource has been created on the origin server, the body of the message SHOULD describe and link to the new resource(s), and in the case of a POST, must have a Location header with a value of the new resource URI.

d. 204 (No content): No content is in the response message body, and this was not in response to a resource creation (201).

e. 206 (Partial Content): occurs if the response is the result of an If-Range request that used a strong cache validator. The response SHOULD NOT include other entity-headers. If the response is the result of an If-Range request that used a weak validator, the response MUST NOT include other entity-headers; this prevents inconsistencies between cached entity bodies and updated headers.

4. Successful PUT responses shall return the following codes:a. 200 (OK) or 204(No Content): they are used when the existing resource has been

replaced.b. 201 (Created): MUST be used when a new resource is created.c. 202 (Accepted): The request has been accepted for processing, but the

processing has not been completed. The request might or might not eventually be acted upon, as it might be disallowed when processing takes place.

5. Successful DELETE responses shall return the following codes:

of 26



a. 200 (OK): for a successful response if the response includes a message body describing the status.

b. 202 (Accepted): The request has been accepted for processing, but the processing has not been completed. The request might or might not eventually be acted upon, as it might be disallowed when processing takes place.

c. 204 (No Content): if the action has been enacted but the response does not include a message body.

5.5.5.10.3 Error Status Code Requirements: 1. Upon error, one of the following codes shall be returned. In favor of a fail-fast design,

4XX error codes should take precedence over 5XX error codes. The API Platform exposure infrastructure will handle throwing 3XX error codes. When an application layer needs to return a specific 3XX error code, they can seek an exception. There is also job aid that assists in describing what HTTP Status Codes apply to which HTTP methods (verbs) at https://wiki.web.att.com/display/DPS/HTTP+Status+Code+to+HTTP+Method+Mapping

2. Error 4XX (Client Error) Response Code Decision Trees

of 26



a. 400 (Bad Request): Many possible reasons not specified by the other codes.b. 401 (Unauthorized): Authentication failed or was not provided in the Authorization

headerc. 403 (Forbidden): The client has insufficient permissions to access the resource.d. 404 (Not Found): The server has not found anything matching the Request-URI.

No indication is given of whether the condition is temporary or permanent.

- See Structured text representation of empty collections in the Content section for empty collection requirements

e. 405 (Method Not Allowed): A request was made of a resource using a request method not supported by that resource (e.g., using PUT on a resource that does not have PUT implemented).

of 26



f. 406 (Not Acceptable): A request was made of a resource for a message body format (e.g. XML or JSON) that is not supported

g. 409 (Conflict): The request could not be completed due to a conflict with the current state of the resource. This code is only allowed in situations where it is expected that the user might be able to resolve the conflict and resubmit the request.

h. 410 (Gone) If the resource is permanently gone (i.e. resource version has been obsoleted), then an HTTP 410 shall be returned indicating to the application that it is permanently gone, and the application should not retry.

i. 411 (Length Required): The Content-Length header was not specified.j. 412 (Precondition Failed): The condition specified in the conditional header(s) was

not met.k. 413 (Request Entity Too Large): The size of the request body exceeds the

maximum size permitted.l. 414 (Request URI Too Long): The Request-URI is longer than the server is willing

to interpret.m. 415 (Unsupported Media Type): The request is in a format not supported by the

target resource for the HTTP method.n. 416 (Requested Range Not Satisfiable): The request included a Range request-

header field, and none of the range-specifier values in this field overlap the current extent of the selected resource, and the request did not include an If-Range request-header field.

o. 423 (Locked): The request exceeded defined thresholds (e.g., requests per month) established by policy or terms and conditions associated with the API.

3. Error 5XX (Server Error) Response Code Decision Trees

a. 500 (Internal Server Error): The server encountered an internal error or timed out; please retry.

b. 501 (Not Implemented): The server either does not recognize the request method, or it lacks the ability to fulfill the request.

c. 503 (Service Unavailable): The server is currently unable to receive requests; please retry.

of 26

nicholasarodriguez.files.wordpress.com · web view2020. 9. 10. · alternatively, the http...

Documents