Commit 668ba70f authored by Siebers, Michael's avatar Siebers, Michael
Browse files

documented JSON parsing limitations

parent f62b4c9d
......@@ -140,7 +140,6 @@ curl --request GET 'http://localhost:4444/bg/show'
| --- | --- | --- | --- |
| _item_ or an array of _item_ | _see example call_ | Required | Asserts the arguments to the background knowledge.|
#### Return value
| Case | Code | Description | Response Body |
......@@ -453,6 +452,15 @@ curl --request GET 'http://localhost:4444/state'
}
```
## Limitations {#limitations}
### Request Bodies with JSON
The current implementation restricts the JSON content of request bodies. Only the first JSON _entity_ is parsed, the remaining text in the body is *silently* discarded. The parsed entity may be of any basic JSON type, like a string, an object, or an array. This may lead to unexpected results on erroneous input. For example, the incomplete array =|1,2,3]|= would be parsed as the integer `1` while the remainig characters are ignored without warning.
However, this limitation only affects the body as a whole. For instance, the body =|{"key": 1,2,3]}|= results in a parsing error since JSON properties must be strings (and `2` is not).
### JSON Arrays
Unlike the JSON standard, the JSON parser ignores a trailing comma in arrays.
## Documentation {#documentation}
When started with the =|--documentation|= switch, the WebAPI server serves its own documentation as HTML pages. The documentation can be accessed using =GET= requests, for example using a conventional web browser.
......
......@@ -3,14 +3,23 @@
%! read_json_body(+Request, -Payload) is det
%
% Read JSON body from request. Only the first object of the body is parsed. Further content is discarded (up to the sent content length). No checks on Payload are performed.
% Read JSON body from request. Only the first entity of the body is parsed.
% Further content is discarded (up to the sent content length). No checks on
% Payload are performed.
%
% Discarding body content after the first JSON _entity_ (meaning integer,
% string, object, ...) is an undocumented feature of the used library predicate
% http_read_json_dict/2. Additionally, the library predicate ignores trailing
% commas in JSON arrays which should be an error.
%
% @throws parse_error(illegal_json_syntax(Details), Position) if request body is
% syntactically illformatted. Position is the term
% stream_position(Line, Column).
% @throws `empty_request_body` if the request has no body
% @throws `length_required` if the request has no Content-Length header
% @throws invalid_header_value(content_length, Value) if a Content-Length header has been sent but the given value Value is invalid (no nonnegative integer).
% @throws invalid_header_value(content_length, Value) if a Content-Length header
% has been sent but the given value Value is invalid (no nonnegative
% integer).
read_json_body(Request, Payload) :-
( memberchk(content_length(Len), Request)
-> ( integer(Len),
......@@ -32,9 +41,13 @@ read_json_body(Request, Payload) :-
%! purge_input_stream(+Request) is det.
%
% Purge the content of the request body. Only possible if a =Content-Length=-header has been sent. If none is sent it is assumed that no payload has been sent.
% Purge the content of the request body. Only possible if a
% =Content-Length=-header has been sent. If none is sent it is assumed that no
% payload has been sent.
%
% @throws invalid_header_value(content_length, Value) if a Content-Length header has been sent but the given value Value is invalid (no nonnegative integer).
% @throws invalid_header_value(content_length, Value) if a Content-Length header
% has been sent but the given value Value is invalid (no nonnegative
% integer).
purge_input_stream(Request) :-
memberchk(input(StreamIn), Request),
memberchk(content_length(Len), Request),
......@@ -52,10 +65,14 @@ purge_input_stream(_).
%! parse_parameters(+In, ++Type, -Out) is det.
%
% Parse input parameters In to the expected type (including dict's optional and required keys).
% Parse input parameters In to the expected type (including dict's optional and
% required keys).
%
% @throws parse_error(Reason, Location) if some part (al location Location) cannot be parsed to the desired type.
% @error api_error(_, parameter_error) if there is an error in the Type specification or some part of the input is unbound which is not allowed by Type.
% @throws parse_error(Reason, Location) if some part (al location Location)
% cannot be parsed to the desired type.
% @error api_error(_, parameter_error) if there is an error in the Type
% specification or some part of the input is unbound which is not allowed
% by Type.
parse_parameters(In, Type, Out) :-
catch(parse_type(In, Type, Out),
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment