cloudfinger
cloudfinger copied to clipboard
Add an API to allow inserting / updating / deleting mappings
Need a simple API that allows for programmatic updating of the mappings. This will initially be used from the command line (e.g. curl
, and be secured by the same pre-shared-key AUTH_TOKEN
that the current /api/list
uses.
How
Add the following operations:
-
/api/get/:from
- GET the single mapping from a specific id (e.g. the mapping for [email protected]) -
/api/add
- POST a new mapping with both a from and to in the POST body* -
/api/update/:from
- PUT an updated mapping with the new values for both the from and to in the PUT body* -
/api/delete/:from
- DELETE an existing mapping of the specified from value
Notes
POST for the add operation
URI: /api/add
- no additional parameters needed
Body:
{
"from": "[email protected]",
"to": "@[email protected]"
}
Result:
{
"success": true,
"errors": [ ]
}
Note: Will return false
with appropriate HTTP Status Code and an explanation in the errors
attribute. A 400-Bad Request
will be returned if either the from or the to are blank or both have the same value. A 409-Conflict
will be returned if the from already has an existing mapping that doesn't match the requested to value. If both the from and to values match a 200-OK
response will be returned (as this is likely a repeated request).
PUT for the update operation
URI: /api/update/:from
where the from value is the from value of an existing mapping. This allow changing a mapping's from or to value at will. An example would be /api/update/[email protected]
.
Body:
{
"from": "[email protected]",
"to": "@[email protected]"
}
Result:
{
"success": true
"errors": [ ]
}
Note: Will return false
with appropriate HTTP Status Code and an explanation in the errors
attribute. 404-Not Found
status code means the URI from value was not in the existing mappings. 409-Conflict
status code means the post-body supplied from value already exists but is NOT the value supplied in the URI (e.g. you tried to change [email protected]'s from to [email protected] and that already has a mapping). If the existing mapping matches what was requested in the PUT, a 200-OK
status code will be returned (as this is likely a repeated request).
DELETE for the delete operation
URI: /api/delete/:from
where the from value is the from value of an existing mapping. An example would be /api/update/[email protected]
. There is no DELETE body content
Result:
{
"success": true
"errors": [ ]
}
Note: Will return false
with appropriate HTTP Status Code and an explanation in the errors
attribute. 410 GONE means the URI from value was not in the existing mappings (as this is likely a repeated request).
HTTP Status Codes
Status Code | Description | List | Add | Update | Delete |
---|---|---|---|---|---|
200 OK | Indicates that the request has succeeded. | X | X | X | |
201 Created | Indicates that the request has succeeded and a new resource has been created as a result. | X | |||
204 No Content | The server has fulfilled the request but does not need to return a response body. The server may return the updated meta information. | X | |||
400 Bad Request | The request could not be understood by the server due to incorrect syntax. The client SHOULD NOT repeat the request without modifications. | X | X | X | X |
404 Not Found | The server can not find the requested resource. | X | X | ||
409 Conflict | The request could not be completed due to a conflict with the current state of the resource. | X | X | ||
410 Gone | The requested resource is no longer available at the server. | X | X |