Skip to content

Commit

Permalink
minor wording changes
Browse files Browse the repository at this point in the history
  • Loading branch information
Erik Wilde committed Apr 28, 2015
1 parent e0a8c73 commit f46e249
Showing 1 changed file with 2 additions and 2 deletions.
4 changes: 2 additions & 2 deletions service-link-rel/draft-wilde-service-link-rel-01.xml
Expand Up @@ -28,7 +28,7 @@
<section title="Introduction" anchor="introduction">
<t>One of the defining aspects of the Web is that it is possible to interact with Web resources without any prior knowledge of the specifics of the resource. By using URIs, HTTP, and media types, the Web's uniform interface allows interactions with resources without the more complex binding procedures of other approaches.</t>
<t>However, many resources on the Web are provided as part of a set of resources that are referred to as a "Web Service" or a "Web API". In many cases, these services or APIs are defined and managed as a whole, and it may be desirable for clients to be able to discover this service definition information.</t>
<t>Service definition can be separated into two broad categories: One category is targeted for human users and often uses generic formats or human readable documents, such as HTML or PDF. The other category is structured information that followed some more formalized description model, and is intended for consumption by machines, for example for tools and code libraries.</t>
<t>Service definition can be separated into two broad categories: One category is targeted for human users and often uses generic formats for human readable documents, such as HTML or PDF. The other category is structured information that followed some more formalized description model, and is intended for consumption by machines, for example for tools and code libraries.</t>
<t>In the context of this specification, the human-oriented variant is referred to as "documentation", and the machine-oriented variant is referred to as "description".</t>
<t>These two categories are not always mutually exclusive, as there are formats that have been proposed that are intended for both human consumption, and for interpretation by machine clients.</t>
<t>This specification places no constraints on the specific formats used for either of those two categories. It simply allows publishers of a Web service to make the documentation and/or the description of their service discoverable, and defines two link relations that serve that purpose.</t>
Expand All @@ -46,7 +46,7 @@
<t>Documentation is often structured, but the exact kind of structure depends on the structure of the service that is documented, as well as on the specific way in which the documentation authors choose to document it.</t>
</section>
<section title="Describing Web Services" anchor="desc-web-services">
<t>In the context of this specification, "description" refers to information that is intended for machine consumption. Typical formats for this are dictated by the technology underlying the service itself, which means that in today's format landscape, description formats exist in XML, JSON, RDF, and a variety of other languages.</t>
<t>In the context of this specification, "description" refers to information that is intended for machine consumption. Typical formats for this are dictated by the technology underlying the service itself, which means that in today's technology landscape, description formats exist that are based on XML, JSON, RDF, and a variety of other languages. Also, in each of those technologies, there may be a variety of languages that are defined to achieve the same general purpose of describing a Web service.</t>
<t>Descriptions are always structured, but the structuring principles depend on the nature of the described service. For example, one of the earlier service description approaches, the Web Services Description Language (WSDL), uses "operations" as its core concept, which are essentially identical to function calls, because the underlying model is based on that of Remote Procedure Calls (RPC). Other description languages for non-RPC approaches to services will use different structuring approaches.</t>
</section>
</section>
Expand Down

0 comments on commit f46e249

Please sign in to comment.