REpresentational State Transfer (REST) is a software architectural style utilised by RESTfm to provide Create, Read, Update and Delete (CRUD) functionality over HTTP.

The World Wide Web is the largest implementation of a REST architecture. Common web browsing utilises the HTTP method 'GET' when loading a web page.

CRUD operations map well to HTTP methods.

Operation HTTP method
Create POST
Read GET
Update PUT
Delete DELETE

Resource URIs

RESTfm utilises a hierarchy of Uniform Resource Identifiers (URIs) to progressively drill down from a list of databases to a single record. Each URI defines a resource.

  • http://example.com/RESTfm/
  • http://example.com/RESTfm/{database}
  • http://example.com/RESTfm/{database}/layout
  • http://example.com/RESTfm/{database}/layout/{layout}
  • http://example.com/RESTfm/{database}/layout/{layout}/{recordID}

A special case URI is provided for calling scripts.

  • http://example.com/RESTfm/{database}/script
  • http://example.com/RESTfm/{database}/script/{script}/{layout}

HTTP Status Codes

RESTfm uses HTTP status codes for all operations. Where FileMaker errors map well to HTTP status codes, they are used. Where there is no equivalent, RESTfm falls back to 500 (Internal Server Error) and provides the FileMaker error details in the response.

Status Code Reason Phrase Description
200 OK Standard response for successful HTTP requests.
201 Created The request has been fulfilled and resulted in a new resource being created.The newly created resource can be referenced by the URI returned in the response.
401 Unauthorized The request requires user authentication.
403 Forbidden RESTfm will respond to non-html formats with '403 Forbidden' instead of '401 Unauthorized', to prevent browsers from popping up authentication dialogues in web applications. This setting may be overridden in the RESTfm.ini.php config file.
404 Not Found The server has not found anything matching the request URI.
500 Internal Server Error
 OR
FileMaker Error
The server encountered an unexpected condition which prevented it from fulfilling the request. This error typically occurs when FileMaker has returned an error. Further inspection of the response message is needed to identify the FileMaker error.

Error Responses

RESTfm returns error information in several ways.

  1. The HTTP Status Code should always be used as indication of success or failure. Error 500 requires further inspection to identify the underlying FileMaker error.
  2. The HTTP Headers contain a copy of the RESTfm and FileMaker Status Codes and Status Reasons.
  3. The formatted response from RESTfm contains a copy of the RESTfm and FileMaker Status Codes and Status Reasons.

Example HTTP Headers

X-RESTfm-Version: 2.0.1/r280
X-RESTfm-Protocol: 4
X-RESTfm-Method: GET
X-RESTfm-Status: 401
X-RESTfm-Reason: Unauthorized
X-RESTfm-FM-Status: 18
X-RESTfm-FM-Reason: Client must provide account information to proceed

Example formatted RESTfm response

Root URI - JSON - Unauthorized

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
    "data": [
        
    ],
    "meta": [
        
    ],
    "info": {
        "X-RESTfm-FM-Status": "18",
        "X-RESTfm-FM-Reason": "Client must provide account information to proceed",
        "X-RESTfm-Version": "2.0.1\/r280",
        "X-RESTfm-Protocol": "4",
        "X-RESTfm-Status": 401,
        "X-RESTfm-Reason": "Unauthorized",
        "X-RESTfm-Method": "GET"
    }
}

Changelog

Version Description
< 2.0.0 Prior to version 2.0.0 the error response format simply appeared as:
Error 401 (18: Client must provide account information to proceed)
  • "Error 401" is the HTTP Status Code
  • "18: Client must provide account information to proceed" is the FileMaker Status Code and Message