REST, URIs, Status Codes and Error Responses
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}
- 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.- 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.
- The HTTP Headers contain a copy of the RESTfm and FileMaker Status Codes and Status Reasons.
- 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
{
"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)
|