Documentation Powered by ReDoc

Mangrove Server API (0.2.0)

Download OpenAPI specification:Download

Open Reviews Association: hello@open-reviews.net License: Apache License 2.0

Submit and retrieve reviews, as well as aggregate statistics about reviews. More information about the values and types can be found in the Open Reviews Standard. For more description and example usage see Mangrove Demo UI and Mangrove Client JS Library for a JavaScript wrapper of this API.

Common

index

Responses

Response Schema: text/plain
string
Response Schema: text/plain
string

Review

Retrieve aggregates for multiple subjects or issuers.

Request Body schema: application/json
subs
required
arraynull

A map from Review identifiers (urn:maresi:<signature>) to information about the reviews of that review.

List of subject URIs to get information about.

pems
required
arraynull

List of issuer public keys to get information about.

Query allowing for retrieval of information about multiple subjects or issuers.

Responses

Response Schema: application/json
issuers
objectnull

Map of issuer public keys to issuer information.

subjects
objectnull

Map of subject identifiers to subject information.

Response Schema: text/plain
string
Response Schema: text/plain
string

Request samples

Content type
application/json
{
  • "pems": null,
  • "subs": null
}

Response samples

Content type
application/json
{
  • "issuers": null,
  • "subjects": null
}

Request reviews within provided coordinates.

query Parameters
xmin
required
number <float>

Minimum longitude

ymin
required
number <float>

Minimum latitude

xmax
required
number <float>

Maximum longitude

ymax
required
number <float>

Maximum latitude

Responses

Response Schema:
application/json
application/json
application/n-triples
required
Array of objects (Review)

A list of reviews satisfying the Query.

issuers
objectnull

A map from public keys to information about issuers.

maresi_subjects
objectnull

A map from Review identifiers (urn:maresi:<signature>) to information about the reviews of that review.

Response Schema: text/plain
string
Response Schema: text/plain
string

Response samples

Content type
application/json
application/json
application/n-triples
{
  • "issuers": null,
  • "maresi_subjects": null,
  • "reviews": [
    • {
      • "jwt": "string",
      • "kid": "string",
      • "payload": {
        • "action": null,
        • "iat": 0,
        • "images": null,
        • "metadata": null,
        • "opinion": null,
        • "rating": null,
        • "sub": "http://example.com"
        },
      • "signature": "string"
      }
    ]
}

Request aggregate information about the reviewer.

path Parameters
pem
required
string
Example: -----BEGIN PUBLIC KEY-----MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEDo6mN4kY6YFhpvF0u3hfVWD1RnDElPweX3U3KiUAx0dVeFLPAmeKdQY3J5agY3VspnHo1p/wH9hbZ63qPbCr6g==-----END PUBLIC KEY-----

Request aggregate information about the reviewer.

Responses

Response Schema: application/json
count
required
integer >= 0

Number of reviews written by this issuer.

credibility
number <float> [ 0 .. 1 ]

Credibility score for this reviewer based on review quality.

Response Schema: text/plain
string
Response Schema: text/plain
string

Response samples

Content type
application/json
{
  • "count": 0,
  • "credibility": 0
}

Request review with the specified signature.

path Parameters
signature
required
string
Example: PDSpnKtHioXykdBCMA15y5cLuYrRbSexscvySt_ryjppDWaW1I1AijjWercZE6K-cbS18bCwSmgIPqRIuL-cow

Signature of the review being requested.

Responses

Response Schema:
application/json
application/json
application/n-triples
signature
required
string

JWT signature by the review issuer.

jwt
required
string <JWT>

Review in JWT format.

kid
required
string

Public key of the reviewer in PEM format.

required
object

Primary content of the review.

Response Schema: text/plain
string
Response Schema: text/plain
string
Response Schema: text/plain
string

Response samples

Content type
application/json
application/json
application/n-triples
{
  • "jwt": "string",
  • "kid": "string",
  • "payload": {
    • "action": null,
    • "iat": 0,
    • "images": null,
    • "metadata": null,
    • "opinion": null,
    • "rating": null,
    • "sub": "http://example.com"
    },
  • "signature": "string"
}

Request reviews matching the provided query.

query Parameters
q
string
Example: q=restaurants in zurich

Search for reviews that have this string in sub or opinion field.

signature
string

Review with this signature value.

kid
string
Example: kid=-----BEGIN PUBLIC KEY-----MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEDo6mN4kY6YFhpvF0u3hfVWD1RnDElPweX3U3KiUAx0dVeFLPAmeKdQY3J5agY3VspnHo1p/wH9hbZ63qPbCr6g==-----END PUBLIC KEY-----

Reviews by issuer with the following PEM public key.

iat
integer <int64>

Reviews issued at this UNIX time.

gt_iat
integer <int64>

Reviews with UNIX timestamp greater than this.

sub
string <uri>

Reviews of the given subject URI.

rating
integer <int16> [ 0 .. 100 ]

Reviews with the given rating.

opinion
string

Reviews with the given opinion.

limit
integer <int64>

Maximum number of reviews that will be returned.

opinionated
boolean

Only reviews which either contain or do not contain an opinion.

examples
boolean

Include reviews left for example subjects https://example.com and geo:0,0?q=*u=*.

issuers
boolean

Include aggregate information about review issuers.

maresi_subjects
boolean

Include aggregate information about reviews of returned reviews.

latest_edits_only
boolean

For edited reviews, return only the most recent version (true by default)

Responses

Response Schema:
application/json
application/json
application/n-triples
text/csv
required
Array of objects (Review)

A list of reviews satisfying the Query.

issuers
objectnull

A map from public keys to information about issuers.

maresi_subjects
objectnull

A map from Review identifiers (urn:maresi:<signature>) to information about the reviews of that review.

Response Schema: text/plain
string
Response Schema: text/plain
string

Response samples

Content type
application/json
application/json
application/n-triples
text/csv
{
  • "issuers": null,
  • "maresi_subjects": null,
  • "reviews": [
    • {
      • "jwt": "string",
      • "kid": "string",
      • "payload": {
        • "action": null,
        • "iat": 0,
        • "images": null,
        • "metadata": null,
        • "opinion": null,
        • "rating": null,
        • "sub": "http://example.com"
        },
      • "signature": "string"
      }
    ]
}

Request aggregate information about the subject.

path Parameters
sub
required
string
Example: https://nytimes.com

Request aggregate information about the subject.

Responses

Response Schema: application/json
sub
required
string <uri>

URI uniquely identifying the subject.

quality
required
integernull <int16>

Aggregate number representing quality of the subject.

count
required
integer <uint> >= 0

Number of reviews given to this subject.

opinion_count
required
integer <uint> >= 0

Number of reviews which included an opinion.

positive_count
required
integer <uint> >= 0

Number of reviews with rating above 50 given to this subject.

confirmed_count
required
integer <uint> >= 0

Number of reviews with rating above 50 and is_personal_experience flag given to this subject.

Response Schema: text/plain
string
Response Schema: text/plain
string

Response samples

Content type
application/json
{
  • "confirmed_count": 0,
  • "count": 0,
  • "opinion_count": 0,
  • "positive_count": 0,
  • "quality": null,
  • "sub": "http://example.com"
}

Submit a new review or perform actions on existing reviews

This endpoint handles multiple operations through the JWT payload structure:

1. Submit a new review - JWT payload contains:

{
  "iat": 1580910022,
  "sub": "https://example.org",
  "rating": 75,
  "opinion": "Great website for reviews."
}

2. Rate an existing review - JWT payload contains:

{
  "iat": 1580910450,
  "sub": "urn:maresi:7xQtIlHuDdCVioyztj8i...",
  "rating": 90
}

This allows users to rate other people's reviews. Note that there is no "action" field here - simply providing a rating with an "urn:maresi:" subject indicates your rating an existing review.

3. Delete an existing review - JWT payload contains:

{
  "iat": 1580910500,
  "sub": "urn:maresi:7xQtIlHuDdCVioyztj8i...",
  "action": "delete"
}

Must be signed with the same key as the original review.

4. Edit an existing review - JWT payload contains:

{
  "iat": 1580910400,
  "sub": "urn:maresi:7xQtIlHuDdCVioyztj8i...",
  "action": "edit",
  "rating": 80,
  "opinion": "Updated opinion text..."
}

Must be signed with the same key as the original review.

5. Report abuse for a review - JWT payload contains:

{
  "iat": 1580910600,
  "sub": "urn:maresi:7xQtIlHuDdCVioyztj8i...",
  "action": "report_abuse",
  "opinion": "This review contains promotional content..."
}

Can be signed with any valid key.

path Parameters
jwt_review
required
string
Example: eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Ii0tLS0tQkVHSU4gUFVCTElDIEtFWS0tLS0tTUZrd0V3WUhLb1pJemowQ0FRWUlLb1pJemowREFRY0RRZ0FFcDc4Zms1eUNqYmlZYXZ5UjZGQ2xxcTlBRkJUaXpBSG1ZdU9rcTR3cy9aYmdleG41SVQ2bi83NGt2YlZ0UGxNc3A5Z2luTysxMVZ4ZUorbVFJQ1pZamc9PS0tLS0tRU5EIFBVQkxJQyBLRVktLS0tLSIsImp3ayI6IntcImNydlwiOlwiUC0yNTZcIixcImV4dFwiOnRydWUsXCJrZXlfb3BzXCI6W1widmVyaWZ5XCJdLFwia3R5XCI6XCJFQ1wiLFwieFwiOlwicDc4Zms1eUNqYmlZYXZ5UjZGQ2xxcTlBRkJUaXpBSG1ZdU9rcTR3c19aWVwiLFwieVwiOlwiNEhzWi1TRS1wXy0tSkwyMWJUNVRMS2ZZSXB6dnRkVmNYaWZwa0NBbVdJNFwifSJ9.eyJpYXQiOjE1ODA5MTAwMjIsInN1YiI6Imh0dHBzOi8vbWFuZ3JvdmUucmV2aWV3cyIsInJhdGluZyI6NzUsIm9waW5pb24iOiJHcmVhdCB3ZWJzaXRlIGZvciByZXZpZXdzLiIsIm1ldGFkYXRhIjp7Im5pY2tuYW1lIjoiam9objEyMyIsImNsaWVudF9pZCI6Imh0dHA6Ly9sb2NhbGhvc3Q6MzAwMCJ9fQ.7xQtIlHuDdCVioyztj8i3zJ8dk3oCSfKr6VCR5RtBn6sBcqvpfyvs13PlKGJoamKzx8xUgQTQJjRPv5s91-VLQ

Mangrove Review in JSON Web Token format as described in the Open Reviews Standard. Please use https://example.com or geo:0,0?q=*&u=* in subject sub field for test reviews which should be removed later.

Responses

Response Schema: text/plain
boolean
Response Schema: text/plain
string
Response Schema: text/plain
string