Service Metadata
CategoryWeb Services Standards
A machine processable description of application service contracts facilitates the API adoption in mixed environments spanning the boundaries of internal systems and hosting providers. Application interactions are most efficient when based on protocol-independent data syntax.
Standards Overview
Standard Web Service and Resource Definitions
When properly defined using industry-standard open formats, application services allow their consumers to discover and understand the interface capabilities without requiring access to source code, comprehensive documentation or inspection of network traffic. A number of widely-used API schema specifications define a format for describing web services as a set of endpoints operating on document-oriented request/response messages.
More traditional web services description languages define application interfaces bound to message-oriented protocols such as SOAP, where the payload is represented predominantly with XML documents. The new wave of web APIs relies directly on communication transports such as HTTP, defining messages based on JSON or YAML data interchange syntax, where web resources can be accessed using simple REST-style operations. The new-style API metadata encourages reuse, enables pattern-sharing, and aims for emergence of best practices.
The following publications standardize application service protocols and data formats:
- ISO/IEC 8859-1 — 8-bit Single-byte Coded Graphic Character Sets - Latin Alphabet No. 1
- ISO/IEC 8859-2 — 8-bit Single-byte Coded Graphic Character Sets - Latin Alphabet No. 2
- ISO/IEC 8859-3 — 8-bit Single-byte Coded Graphic Character Sets - Latin Alphabet No. 3
- ISO/IEC 8859-4 — 8-bit Single-byte Coded Graphic Character Sets - Latin Alphabet No. 4
- ISO/IEC 8859-5 — 8-bit Single-byte Coded Graphic Character Sets - Latin/Cyrillic Alphabet
- ISO/IEC 8859-6 — 8-bit Single-byte Coded Graphic Character Sets - Latin/Arabic Alphabet
- ISO/IEC 8859-7 — 8-bit Single-byte Coded Graphic Character Sets - Latin/Greek Alphabet
- ISO/IEC 8859-8 — 8-bit Single-byte Coded Graphic Character Sets - Latin/Hebrew Alphabet
- ISO/IEC 8859-9 — 8-bit Single-byte Coded Graphic Character Sets - Latin Alphabet No. 5
- ISO/IEC 8859-10 — 8-bit Single-byte Coded Graphic Character Sets - Latin Alphabet No. 6
- ISO/IEC 8859-11 — 8-bit Single-byte Coded Graphic Character Sets - Latin/Thai Alphabet
- ISO/IEC 8859-13 — 8-bit Single-byte Coded Graphic Character Sets - Latin Alphabet No. 7
- ISO/IEC 8859-14 — 8-bit Single-byte Coded Graphic Character Sets - Latin Alphabet No. 8
- ISO/IEC 8859-15 — 8-bit Single-byte Coded Graphic Character Sets - Latin Alphabet No. 9
- ISO/IEC 8859-16 — 8-bit Single-byte Coded Graphic Character Sets - Latin Alphabet No. 10
- ISO/IEC 10646 — Universal Coded Character Set (UCS)
- ISO/IEC 21778 — JSON Data Interchange Syntax
- ISO/IEC 29361 — Web Services Interoperability - WS-I Basic Profile
- ISO/IEC 29362 — Web Services Interoperability - WS-I Attachments Profile
- ISO/IEC 29363 — Web Services Interoperability - WS-I Simple SOAP Binding Profile
- ISO/IEC 16680 — TOG Service Integration Maturity Model (OSIMM)
- ISO/IEC 18384-1 — Reference Architecture for SOA - Terminology and Concepts
- ISO/IEC 18384-2 — Reference Architecture for SOA - SOA Solutions
- ISO/IEC 18384-3 — Reference Architecture for SOA - SOA Ontology
- RFC 3629 — UTF-8, a Transformation Format of ISO 10646
- RFC 2781 — UTF-16, an Encoding of ISO 10646
- RFC 2822 — Internet Message Format
- RFC 2045 — MIME: Format of Internet Message Bodies
- RFC 2046 — MIME: Media Types
- RFC 3986 — URI: Generic Syntax
- RFC 7320 — URI: Design and Ownership
- RFC 8259 — JSON Data Interchange Format
- JSON Schema Core
- JSON Schema Validation
- JSON Hyper-Schema
- Relative JSON Pointers
- WADL — Web Application Description Language (WADL)
- WSDL 1.1 — Web Services Description Language (WSDL) 1.1
- WSDL 2.0 - Core — Web Services Description Language (WSDL) 2.0 - Core Language
- WSDL 2.0 - Adjuncts — Web Services Description Language (WSDL) 2.0 - Adjuncts
- WS-Policy 1.2 — Web Services Policy 1.2 - Framework
- WS-PolicyAttachment 1.2 — Web Services Policy 1.2 - Attachment
- WS-MetadataExchange — Web Services Metadata Exchange
- XSD 1.1: Structures — XML Schema Definition Language (XSD): Structures
- XSD 1.1: Datatypes — XML Schema Definition Language (XSD): Datatypes
- WS-Resource 1.2 — Web Services Resource 1.2
- WS-ResourceProperties 1.2 — Web Services Resource Properties 1.2
- WS-ResourceLifetime 1.2 — Web Services Resource Lifetime 1.2
- WS-ServiceGroup 1.2 — Web Services Service Group 1.2
- WS-BaseFaults 1.2 — Web Services Base Faults 1.2
- WS-ResourceMetadataDescriptor 1.0 — Web Services Resource Metadata 1.0
- SOA-RAF 1.0 — Reference Architecture Foundation for Service Oriented Architecture 1.0
- SOA-RM 1.0 — Reference Model for Service Oriented Architecture 1.0
metadata
An API schema is intended to define structure, validation, documentation, hyperlink navigation and interaction control of the exchanged information.
With clearly defined API endpoints, a service consumer can understand and interact with the remote service with a minimal amount of client implementation logic.
An API is typically described by a schema document, or a set of documents, and operations that define how messages relate to each other in the callout sequence.
Industry-standard API definitions can be used for documentation generation, source code generation and automated service testing.
New wave of data interchange formats is human-friendly and allows the data to show itself in a meaningful way.