What is a REST API?
API is an abbreviation for "Application Programming Interface". An API is a set of rules that lets programs talk to each other, exposing data and functionality across the Internet in a consistent format.
REST stands for "Representational State Transfer". This is an architectural pattern that describes how distributed systems
can expose a consistent interface. When people use the term "REST API", they are generally referring to an API accessed using the HTTP protocol at a predefined set of URLs.
These URLs represent various resources — any information or content accessed at that location, which can be returned as JSON, HTML, audio files, or images. Often resources have one or more methods that can be performed on them
over HTTP, like
GET, POST, PUT, and DELETE. The action represented by the first and last of these is clear, but POST and PUT have specific meanings. How they are defined is
confusing, but the general rule is: use POST to create resources, and PUT to update
resources.
Real&Mate, for example, provides many separate REST APIs for managing application, getting information about real estate objects, adding new real estate objects and a whole lot more. In Real&Mate ecosystem, each service has its
own API, and at the same time you will work with each of them in roughly the same way, directly over HTTP.
Authenticate with HTTP
Real&Mate supports HTTP Basic authentication. This allows you to protect the URLs on your web server so that only you and Real&Mate can
access them. In order to authenticate with HTTP, you may provide a username and password with the following URL format:
https://username:password@api.realandmate.com/yyyy-mm-dd/your_desired_path
For HTTP Basic authentication, you will use your Real&Mate account ID as your username and your auth token as your password:
curl -G https://api.realandmate.com/yyyy-mm-dd/Accounts \
-u '<YOUR_ACCOUNT_ID>:<YOUR_AUTH_TOKEN>'
If you want to use API keys to authenticate instead of your Real&Mate account ID and auth token, then use the API key as your username and your API key’s Secret as your password:
curl -G https://api.realandmate.com/yyyy-mm-dd/Accounts \
-u '<YOUR_API_KEY>:<YOUR_API_KEY_SECRET>'
The API key type has to be created as Base for the above command to access your accounts. Keys of type Common can only be used on commands where you also provide the Account ID as part of the API. For
example:
curl -X GET https://api.realandmate.com/yyyy-mm-dd/Accounts \
'<YOUR_ACCOUNT_ID>/Applications.json' \
-u $'<YOUR_API_KEY>:<YOUR_API_KEY_SECRET>'
Real&Mate will authenticate to your web server using the provided username and password and will remain logged in for the duration of the action.
How Real&Mate’s API uses webhooks
Webhooks are user-defined HTTP callbacks triggered by an event in a web application. Real&Mate uses webhooks to let your application know when events happen, like adding a new
real estate object or updating an existing one. Webhooks are triggered asynchronously.
When the webhook event occurs, Real&Mate makes an HTTP request (usually GET or POST) to the URL you have configured for your webhook. Real&Mate's request to your application includes details of the
event like the body of an log entry or the updated real estate parameters. Your application can then perform whatever logic is necessary, then reply to Real&Mate with a response containing the instructions you’d like Real&Mate to perform.