Cookbutler RESTful Web-service Documentation

# Start

API to receive recipes and recipe data.

# Get API key

Um diese API in vollem Umfang verwenden zu können, benötigst du einen API Schlüssel. Wie du an diesen kommst, erfährst du hier.

# Basic instructions

Bevor du mit den Methoden beginnst, lies dir bitte die Grundeinweisungen durch.

Bei dieser Dokumentation, handelt es sich um eine REST API Dokumentation. In der Regel verarbeiten wir GET und POST Anfragen. Unterschiede kannst du den Methoden entnehmen. Die Anfragen sind Plattform unabhängig. Ob du PHP, Python oder eine andere Skript-Sprache verwendest, spielt für uns keine Rolle. Alle Rückgaben sind im JSON Format. Als Charset verwendet wir UTF-8 und Uhrzeiten sind in der Zeitzone UTC.

API Endpoint: https://api.cookbutler.com/
Die Methoden werden per URI an den Endpoint angehängt.

Jede Anfrage und jede Antwort enthalten Header-Informationen. Manche dieser sind Pflicht, wie z.B. der User-Agent. Andere wiederum Optional. Hier eine Liste der Header-Daten für den Request und den Response:

Liste der akzeptierten Anfrage-Header
Name	Value	Description
Accept-Encoding optional	Accepted: gzip	Komprimiert die zu übertragenden Daten. Der Datentransfer kann aufgrund der kleineren Datengröße schneller durchgeführt werden.
Accept-Version optional	Sample: v1	Zu verwendende Methoden-Version. Jeder Methode hat seine eigene Version. Wenn nicht angegeben, wird immer die aktuellste verwenden.
Authorization optional	Bearer {YOUR-JWT-TOKEN}	Enthält die Authorisierungs-Daten und Methoden-Parameter. Alternativ kann JWT-Token auch mittels GET- oder POST-Parameter "jwt_token" mitgeschickt werden. Wir empfehlen aber den Authorization-Header zu verwenden. Wie der JWT-Token erstellt wird, erfahrt ihr hier.
Content-Type optional	Accepted: application/json	Der Content-Type gibt an in welchen Format ihr uns eure Anfrage schickt. Da wir alle Methoden-Parameter im JWT-Token haben, wird lediglich bei der Methode POST die Angabe von Content-Type benötigt.
User-Agent Required	Sample: "Your Projectname/v1.0"	Wiki

Liste der mitgelieferten Antwort-Header
Name	Value	Description
X-API-Version	Sample: v1	Aktuell verwendete Version der Methode.
X-API-Last-Version	Sample: v1.1	Falls du nicht die aktuellste Version verwendest, wird dir hierüber mitgeteilt, dass es eine neuere Version dieser Methode gibt. Falls du bereits die aktuellste Version verwendest, wird dir diese Angabe nicht mit geschickt.
X-RateLimit-Limit	Sample: 60	Maximale Anzahl Anfragen, welche dir pro Minute zur Verfügung stehen.
X-RateLimit-Remaining	Sample: 50	Noch verfügbare Anzahl an Anfragen bevor dein Client für den Rest des Zeitfensters gesperrt wird.

# Example

Request:

curl -X GET https://api.cookbutler.com/recipes/get-languages \
--header "User-Agent: Sample cURL Request" \
--header "Authorization: Bearer {YOUR-JWT-TOKEN}" \
--output -

Response:

200 Ok

{ "status": "ok", "data": { "total": 1, "languages": { "de-de": "de-de" } } }

# JWT Token

Zur Authorisierung einer Anfrage verwenden wir JWT. Für mehr Informationen über JWT, schaue zuerst auf jwt.io.

# Folgende Algorithmen werden von uns unterstützt:

HS256
HS384
HS512

# Payload

Der Payload enthält deinen API Schlüssel, die Methoden-Parameter und einen Zeitstempel, welchen eine Anfrage nur temporär gültig macht. Weitere Parameter, wie z.B. "jti" sind Optional und werden von uns nicht ausgewertet.

Wichtig: Die Methoden-Parameter können alternativ auch als POST-Parameter, z.B. URL-Encoded oder direkt als JSON-String angehängt werden. Siehe dazu das cURL-Beispiel.

Liste der verwendeten Payload-Parameter.
Name	Description
api_key Required / string	Dein API Schlüssel durch den wir deine Anwendung authentifizieren können.
iat Required / integer	Issues At Wir verwenden die Zeitzone UTC. Bitte achte beim Erstellen des iat-Wertes darauf. Für weitere Informationen schaue bitte hier.
param Required / array	Enthält die Methoden-Parameter.

$algo = "HS256";
$header = ["typ"=>"JWT","alg"=>$algo];
$header = base64UrlEncode(json_encode($header)); # base64UrlEncode() is url safe base64_encode()

$iat_time = time(); # please note that we use the time zone UTC
$param = []; # params for methods
$payload = ["iat"=>$iat_time,"api_key"=>"{YOUR-API-KEY}","param"=>$param];
$payload = base64UrlEncode(json_encode($payload));

$signature = base64UrlEncode(hash_hmac($algo, $header . "." . $payload, "{YOUR-API-SECRET}", true));
$jwt_token = $header . "." . $payload . "." . $signature;

curl --location --request POST '{API-ENDPOINT}' \
--header 'User-Agent: xxx' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {YOUR-JWT-TOKEN}' \
--data-raw '{JSON-DATA}'

# Error Handling

Liste der Status-Codes welche wir verwenden. Für eine genauere Beschreibung, schaue dir die HTTP Statuscodes auf Wikipedia an.
Code	Description
200 OK	Standard response for successful requests.
400 Bad Request	The request cannot be fulfilled due to bad syntax, as sample missing required parameter or wrong type of parameter.
401 Unauthorized	Similar to 403 Forbidden, but specifically for use when authentication is required and has failed or has not yet been provided.
403 Forbidden	The request was valid, but you are not authorized to call this resource.
404 Not Found	The requested resource could not be found but may be available again in the future. Subsequent requests by the client are permissible.
405 Method Not Allowed	The request method is not supported for the requested resource.
412 Precondition Failed	If you send a request with missing header informations like "User-Agent".
500 Internal Server Error	A generic error message, given when no more specific message is suitable, in this case please open a support request.
501 Not Implemented	The server either does not recognize the request method.

# Example

Request:

GET https://api.cookbutler.com/recipes/get-languages

Response:

401 Unauthorized

{ "status": "error", "error": "Authorization was not found" }