Module ocs_rest

Description
Data Types
Function Index
Function Details

This library module implements utility functions for REST servers in the ocs application.

Description

This library module implements utility functions for REST servers in the ocs application.

Data Types

operator()

problem()

problem() = #{type := uri(), title := string(), code := string(), cause => string(), detail => string(), invalidParams => [#{param := string(), reason => string()}], status => 200..599}

timestamp()

timestamp() = pos_integer() | string()

Function Index

date/1	Convert between Unix epoch timestamp and OTP date and time.
iso8601/1	Convert between ISO8601 and unix epoch milliseconds.
etag/1	Map unique timestamp and HTTP ETag.
fields/2	Filter a JSON object.
lhs/1	Parse the left hand side of a query paramater.
range/1	Parse or create a `Range` request header.
pointer/1	Decode JSON Pointer.
patch/2	Apply a JSON `Patch` (RFC6902).
millionths_in/1	Convert monetary value from external to internal format.
millionths_out/1	Convert monetary value from internal to external format.
format_problem/2	Format a problem report in an accepted content type.
query_date/1	Parse a dissected URI query for a date range.
date_range/1	Convert an ISO8601 prefix to a range.

Function Details

date/1

date(DateTime) -> Result

DateTime = timestamp() | calendar:datetime1970()
Result = calendar:datetime() | timestamp()

Convert between Unix epoch timestamp and OTP date and time.

iso8601/1

iso8601(DateTime) -> Result

DateTime = ISO8601 | MilliSeconds
ISO8601 = string()
MilliSeconds = pos_integer()
Result = timestamp()

Convert between ISO8601 and unix epoch milliseconds.

etag/1

etag(Etag) -> Etag

Etag = string() | {TS, N}
TS = pos_integer()
N = pos_integer()

Map unique timestamp and HTTP ETag.

fields/2

fields(Filters, JsonObject) -> Result

Filters = string()
JsonObject = tuple()
Result = tuple()

throws {error, 400}

Filter a JSON object.

Parses the right hand side of a fields= portion of a query string and applies those filters on a JSON object.

Each filter in Filters is the name of a member in the JSON encoded JsonObject. A filter may refer to a complex type by use of the "dot" path separator character (e.g. "a.b.c"). Where an intermediate node on a complex path is an array all matching array members will be included. To filter out objects an =value, suffix may be added which will include only objects with a member matching the name and value. Multiple values may be provided with =(value1,value2).

Returns a new JSON object with only the matching items.

Example:

  	1> In = {struct,[{"a",{array,[{struct,[{"name","bob"},{"value",6}]},
  	1> {stuct,[{"b",7}]},{struct,[{"name","sue"},{"value",5},{"other", 8}]}]}},{"b",1}]},
  	1> ocs_rest:fields("b,a.name=sue,a.value", In).
  	{struct, [{"a",{array,[{struct,[{"name","sue"},{"value",5}]}]}},{"b",1}]}

lhs/1

lhs(String) -> Result

String = string()
Result = {LHS, Operator, RHS}
LHS = string()
Operator = operator()
RHS = string()

Parse the left hand side of a query paramater.

range/1

range(Range) -> Result

Range = RHS | {Start, End}
RHS = string()
Result = {ok, {Start, End}} | {ok, RHS} | {error, 400}
Start = pos_integer()
End = pos_integer()

Parse or create a Range request header. RHS should be the right hand side of an RFC7233 Range: header conforming to TMF630 (e.g. "items=1-100").

pointer/1

pointer(Path) -> Pointer

Path = string()
Pointer = [string()]

Decode JSON Pointer. Apply the decoding rules of RFC6901. Path is a JSON string as used in the "path" member of a JSON Patch ((RFC6902) operation. Pointer is a list of member name strings in a path.

patch/2

patch(Patch, Resource) -> Resource

Patch = {array, [{struct, [tuple()]}]}
Resource = {struct, list()} | {array, list()}

Apply a JSON Patch (RFC6902). Modifies the Resource by applying the operations listed in Patch. Operation may be "add", "remove", or "replace".

millionths_in/1

millionths_in(In) -> Out

In = string() | integer() | float()
Out = millionths()

Convert monetary value from external to internal format.

Monetary values are represented internally as an integer number of a million fractions. This allows for six decimal places of precision while allowing purely integer arithmetic.

A JSON number data type may be integer or float and this function will accept either as input. It also accepts a string representation of the same which is preferable to decimal number as it will avoid floating point arithmetic.

millionths_out/1

millionths_out(In) -> Out

In = millionths()
Out = string()

Convert monetary value from internal to external format.

Monetary values are represented internally as an integer number of a million fractions. This allows for six decimal places of precision while allowing purely integer arithmetic.

The output is a string representation to avoid floating point arithmetic.

format_problem/2

format_problem(Problem, Headers) -> Result

Problem = problem()
Headers = [tuple()]
Result = {ContentType, Body}
ContentType = string()
Body = string()

Format a problem report in an accepted content type.

Problem MUST contain type, title, and code. RFC7807 specifies type as a URI reference to human-readable documentation for the problem type. Use title for a short summary of the problem type. TMF630 mandates code to provide an application related code which may be included in an API specification. 3GPP SBI adds cause and invalidParams.

The result shall be formatted in one of the following media types, in priority order:

ContentType :: "application/problem+json" | "application/json" | "text/html"

query_date/1

query_date(QueryList) -> Result

QueryList = [{Key, Value}]
Key = unicode:chardata()
Value = unicode:chardata() | true
Result = {Start, End}
Start = pos_integer() | undefined
End = pos_integer() | undefined

throws {error, 400}

Parse a dissected URI query for a date range.

Parse date key(s), possibly with operators, to derive a date range.

date_range/1

date_range(ISODateTime) -> Result

ISODateTime = string()
Result = {Start, End}
Start = pos_integer()
End = pos_integer()

Convert an ISO8601 prefix to a range.

Generated by EDoc