Skip to content

Latest commit

 

History

History
89 lines (78 loc) · 3.99 KB

Protocol.md

File metadata and controls

89 lines (78 loc) · 3.99 KB
Raw

Applin Protocol

Applin clients and servers communicate with JSON and HTTP. It incorporates the core concepts of REST.

Pages and URLs

Every Applin app is accessible at a particular base URL with the form https://NETADDR/PATH. The URL must not contain query or fragment components.

Every Applin app page has a URL. All page URLs are relative to the base URL.

When an Applin app starts up, it displays the "home page" which is at relative URL /. An Applin app displays Applin pages only from the base URL. To display content from another server, you can use a Markdown page.

For example, if your app's base URL is https://applin.example.com:1234/travel1 then the relative URL /foo corresponds to the absolute URL https://applin.example.com:1234/travel1/foo.

Client Role

Every Applin client is a program that makes requests to a particular Applin server, receives page specifications from the server, and provides functions for interacting with pages and navigating between pages.

Request types:

  • GET for a page the client has not previously requested
    • Request headers
  • GET to refresh a page that has no variables
    • Request headers
      • Accept: application/vnd.applin_response
  • POST to refresh a page that has variables.
    • Request headers
      • Accept: application/vnd.applin_response
      • Content-Type: application/json request header
    • Request body is a JSON object with the current page's variables.
  • POST for a rpc action on a button.
    • Request headers
      • Content-Type: application/json request header
    • Request body is a JSON object with the current page's variables.
  • GET for page content (images, etc.)

Server Role

Every Applin server is an HTTP server that handles requests.

  • Requests for pages, when request has the Accept: application/vnd.applin_response header
    • Response headers
      • Content-Type: application/vnd.applin_response
      • Response code: 200 OK
      • Response body is a JSON object with the format described below.
      • Do not return 4xx errors for bad user input. Instead, display problems on the page.
  • Form POST (without Accept: application/vnd.applin_response)
    • Response code: 200 OK
    • No response body
  • The request is missing a required variable, or a variable has the wrong type
    • Response code: 400 Bad Request
    • Response headers: Content-Type: text/plain
    • Response body: a message for the user
  • User entered data that is unacceptable
    • Response code: 422 Unprocessable Content
    • Response headers: Content-Type: text/plain
    • Response body: a message for the user
  • User is not logged in (session cookie missing or invalid) or does not have permission to view the page
    • Response code: 403 Forbidden
    • Response headers: Content-Type: text/plain
    • Response body: a message for the user
  • Server failed to process the request
    • Response code: 500 Internal Server Error
    • Response headers: Content-Type: text/plain
    • Response body: a message for the user
  • Server is overloaded
    • Response code: 503 Service Unavailable
    • No response body
    • The client will retry with backoff.

Applin clients receive and send cookies like web browsers. Servers can set and receive cookies for session tokens. See Cookies on MDN.

Applin Request Format

The application/json content-type is a JSON object encoded in a UTF-8 string. It contains key-value pairs for all variables defined on the page.

Applin Response Format

The application/vnd.applin_response content-type is a JSON object encoded in a UTF-8 string. It may include these keys:

  • page is an Applin page specification