What are methods?
Methods are the basic constructs that allow you to perform actions or fetch information from Flock. For example, Flock has methods for each of the sample use cases listed below, among others.
- Sending a message to a user or a group;
- Fetching the list of a user's contacts;
- Fetching information about a user or a group.
Similar to methods and function calls in any programming language, Flock methods too receive a list of named parameters, and may optionally return a value.
List of methods available in FlockOS
Calling a method
Flock provides an HTTP endpoint for each API method.
https://api.flock.co/v1/<method-name>
To call a method, send an HTTP GET
or POST
request to the method endpoint, alongwith its parameters (can be either GET
or POST
).
In addition to the method parameters, your app needs to provide the user token using the parameter name token
.
For example, to call chat.sendMessage, you can either send a GET
request to following URL:
https://api.flock.co/v1/chat.sendMessage?to=u:513a9f4ae409&text=hello&token=632542db-1a23-4e06-8b39-01f8b0868d57
Or you can send a POST
request to https://api.flock.co/v1/chat.sendMessage
:
POST /v1/chat.sendMessage HTTP/1.1 Host: api.flock.co Content-Type: application/x-www-form-urlencoded Content-Length: 70 to=u:513a9f4ae409&text=hello&token=632542db-1a23-4e06-8b39-01f8b0868d57
If a method call is successful, the status code 200 is returned in the HTTP response.
Return values
Yes, methods may optionally return a value. A response value is returned as a JSON document in the response body of the HTTP request.
HTTP/1.1 200 OK Content-Type: application/json Content-Length: 51 { "uid": "d9e054e0-a679-4a7a-9cfa-7299669aa083" }
Errors
If an error occurs while processing your request, an HTTP status code other than 200 is returned. Further information about the error is provided by a JSON in the HTTP response body.
HTTP/1.1 400 Bad Request Content-Type: application/json { "error": "MissingParameter", "description": "One or more parameters required for this method call are missing", "parameter": "text" }
Two fields will always be present when an error is returned:
error
– an error codedescription
– a human readable description of the error
Depending on the error code, additional fields may also be present in the JSON if they provide more context. For example, parameter
is an additional field in the response above.
Below is a list of generic error codes that can be returned in response to a method call. Note that some methods can return other errors in addition to these. See individual method pages for more information.
Error Code | HTTP Status | Description | Additional Attributes |
---|---|---|---|
InvalidRequestData | 400 | The request was malformed | |
InvalidParameter | 400 | A parameter for the method call is missing or invalid |
|
MissingUserToken | 400 | Missing user token in the method request | |
InvalidUserToken | 403 | An invalid user token was sent with the request | |
AppDisabled | 403 | App has been disabled for this user |
|
NoSuchMethod | 404 | The method named in the request URL does not exist | |
HTTPMethodNotAllowed | 405 | An HTTP method other than POST was used | |
RequestTimeout | 408 | A timeout occured before the server could receive the complete request from the app | |
TooManyRequests | 429 | Rate limit reached | |
InternalServerError | 500 | An unexpected condition was encountered | |
ServiceUnavailable | 503 | The API service is unavailable at this time |