API Gateway

The API Gateway exposes two endpoints intended to interact with the Local NOSTR Relay.

• {base API url}/nostr/dispatch: the synchronous NOSTR API endpoint.
• {base API url}/nostr/publish: the asynchronous NOSTR API endpoint.

OPTIONS Method

Both endpoints accept an OPTIONS request method with the following response:

HTTP/1.1 204 No Content
Date: {day name}, {day} {month} {year} {hour}:{minute}:{second} GMT
Allow: OPTIONS, POST
{additional headers may be present}

Errors

Upon being requested any method other than OPTIONS or POST, these endpoints respond with:

HTTP/1.1 405 Method Not Allowed
Date: {day name}, {day} {month} {year} {hour}:{minute}:{second} GMT
Allow: OPTIONS, POST
{additional headers may be present}

Both endpoints expect the body to consist of a NOSTR event JSON, if the content cannot be parsed as a valid JSON object, these endpoints respond with:

HTTP/1.1 415 Unsupported Media Type
Date: {day name}, {day} {month} {year} {hour}:{minute}:{second} GMT
{additional headers may be present}

If the request contained an Accept header, and said header indicated a media type other than application/json or (preferably) application/nostr+json, these endpoints respond with:

HTTP/1.1 406 Not Acceptable
Date: {day name}, {day} {month} {year} {hour}:{minute}:{second} GMT
{additional headers may be present}
 
application/json
application/nostr+json

If the request's body can be parsed as a JSON object, but this object does not conform to the NOSTR protocol specification, these endpoints respond with:

HTTP/1.1 422 Unprocessable Content
Date: {day name}, {day} {month} {year} {hour}:{minute}:{second} GMT
{additional headers may be present}

The potential offenses include (but are not limited to):

• missing first-level field: all of the basic NOSTR fields are REQUIRED (ie. .id, .pubkey, .created_at, .kind, .tags, .content, and .sig),
• malformed field values: malformed .id, .pubkey, .created_at, or .sig fields; additionally, malformed .tags contents:
  • a single "k" tag is required,
  • at least one "p" tag is required; additionally, it should not be malformed,
  • at most one "delegation" tag is required; additionally:
    • it should not be malformed,
    • it should validate cryptographically, and
    • the conditions query string should match the actual event, and
  • at most one "alt" tag is required
• malformed .content field

On the other hand, upon successfully parsing and validating the request body, the synchronous NOSTR API endpoint (ie. {base API url}/nostr/dispatch) will apply one more validation:

• there should be EXACTLY ONE "p" tag within the .tags field.

If this validation fails, the endpoint rill respond with:

HTTP/1.1 422 Unprocessable Content
Date: {day name}, {day} {month} {year} {hour}:{minute}:{second} GMT
{additional headers may be present}

Otherwise, the API Gateway will query its internal routing table for the given "p" tag value, if no routing information is found, the endpoint responds with:

HTTP/1.1 421 Misdirected Request
Date: {day name}, {day} {month} {year} {hour}:{minute}:{second} GMT
{additional headers may be present}

Success

Upon successfully parsing and validating the request body, the asynchronous NOSTR API endpoint (ie. {base API url}/nostr/publish) will send an EVENT message to the Local NOSTR Relay (via WebSockets) with the request body as data and respond with:

HTTP/1.1 202 Accepted
Date: {day name}, {day} {month} {year} {hour}:{minute}:{second} GMT
Location: nostr:{nevent}
Content-Length: 0
{additional headers may be present}

Where the nostr:{nevent} value of the Location header conforms to NIP-21: nostr: URI Scheme (opens in a new tab) pointing to the event id in the request body.

On the other hand, if the additional validation succeeded, and routing information is found for the single "p" tag value, the asynchronous NOSTR API endpoint (ie. {base API url}/nostr/publish) will forward the request as-is to the corresponding internal module, and respond with WHATEVER THE MODULE RESPONDED WITH.

NOTE: In this last case, the API Gateway acts as a reverse proxy for the especific request given.