3,018
edits
MikeVislocky (talk | contribs) m (Moved comma) |
MikeVislocky (talk | contribs) (Undo revision 6765 by MikeVislocky (talk) Removed test word.) Tag: Undo |
||
(10 intermediate revisions by 2 users not shown) | |||
Line 1:
NENA-REF-008.1-2020
'''©''' Copyright 2020 National Emergency Number Association, Inc.
Line 12 ⟶ 13:
== Introduction ==
Standards commonly include functionality performed by cooperating entities using a defined interface. For example, NENA i3 specifies a logging function where various elements generate log events that are created and stored by a logging server, and entities are able to retrieve log events from the logging service. In general, such functionality is specified using a network protocol (which allows the entities to be located on the same machine, on different machines, even on different machines in different networks, and to be provided by different vendors). Designers of such protocols may choose to create a new protocol for their purpose (which might be an entirely new protocol or a modification of an existing protocol) or to re-use an existing protocol. When a protocol is reused, the standard specifies how the information for the functionality is conveyed using the existing protocol. Various models are possible, although often such services use a concept of a request and a response, and often the side making a request is referred to as the client, and the side receiving the request and sending a response is referred to as the server. Protocols may be directional (one side initiates requests and the other side responds) or not (either side may send data to the other at any time), and may be synchronous or asynchronous. In synchronous protocols, messages are only sent at defined instances, for example, in synchronous client/server protocols, servers only send messages to clients in response to a request; in some protocols, each response can only result in one response. Asynchronous protocols allow messages to be sent at any time or for multiple responses to be sent to a single request. For example, an HTTP<ref>[https://tools.ietf.org/html/RFC7230 RFC7230 Hypertext Transfer Protocol (HTTP)
In recent years, a common choice for service designers has been to use HTTP over TLS<ref>[https://tools.ietf.org/html/rfc5264 RFC5264 Transport Layer Security (TLS)
NENA work groups (WGs) that design web services typically need to decide how various aspects of the interfaces function. Certain important aspects are described below.
Line 78 ⟶ 79:
</syntaxhighlight>3. Parameters may be encoded within a body part of a request or response.
HTTP messages consist of a header, containing fields, and optionally, a body consisting of a MIME<ref>[https://tools.ietf.org/html/rfc2046 RFC2046 Multipurpose Internet Mail Extensions (MIME)
When encoding parameters within a body part (method 3), virtually any MIME type could be used to contain the parameters. For example, a web service could use a “text/plain” body part, defining a text-based syntax for encoding parameters, or could use a “multipart/form-data” or “application/x-www-form-urlencoded” body part as if sending HTML <form> data. A web service could create and register its own MIME type, with parameters structured using JSON, XML, or any other format. Since web services typically make use of JSON or XML object encoding, parameters are most commonly passed as one or more JSON or XML objects, i.e., as one or more body parts of “application/json”, “text/xml”, “application/xml”, or one of the many more specific MIME types with a subtype containing “+json” or “+xml” (indicating JSON or XML encoding).
Note that passing a body in a GET “has no defined semantics,<ref>[https://tools.ietf.org/html/rfc7231 RFC7231 Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content
The URL (method 1) and header field (method 2) mechanisms are primarily suitable for scalar values (such as strings, numbers, and Booleans), as opposed to complex objects (such as arrays). While complex objects could be encoded into header fields, in practice, the most reasonable solution is to encode them as an object in the body (such as a JSON or XML object).
Line 104 ⟶ 105:
2. PUT
3. PATCH<ref>[https://tools.ietf.org/html/rfc5789 RFC5785 “PATCH Method for HTTP”
4. DELETE
Line 235 ⟶ 236:
For maximum consistency among NENA web services, use the Swagger Hub tool, which supports Open API. NENA has a limited license for this tool; contact the NENA Technical Issues Director for access. Consult the i3 Policy Store and Logging web services for examples of how to structure the YAML file (which defines the web service) to maximize consistency. Also note that the swagger.io<ref name=":0" /> tool is available for free and can be used to develop and validate the correctness of an API.
<br />
== References ==
<references />
[[Category:Technical Guides]]
[[Category:Article]]
[[Category:NENA Reference]]
|