This specification documents the RecipeRPC protocol, version 0.1.

RecipeRPC is a protocol for supplying recipes to clients over a network from one or more central servers. It is:

RecipeRPC clients make remote procedure calls using XML-RPC. You should read the XML-RPC specification before reading this document. (Don't worry, it's short and simple.)

Table of contents

Sample session
Usernames and passwords
Config method
Search method
Recipe request
Optional methods
Odds and ends
Copyright and disclaimer

Sample session

Here is an example of the messages that pass between a RecipeRPC client and a RecipeRPC server in a typical session. To keep the description clear and simple, this sample session shows neither fault handling nor handling of extended result lists.

1A. Client calls the XML-RPC procedure

  struct config("squirrel", "mypassword")

1B. Server returns the struct

Key Value
version 0.1
description RecipeRPC Reference Implementation 0.1
criteria [name, category]
formats [RecipeML, CookML]

2A. Client calls the XML-RPC procedure

  struct search("squirrel", "mypassword", criteria, 1)

where criteria is the struct

Key Value
name spaghetti
category vegetarian

2B. Server returns the struct

Key Value
total 2
recipes See below.

in which recipes is an array containing these two structs:

Key Value
name Mom's Spaghetti
id 12345

and

Key Value
name Spaghetti Medici
id 65432

3A. Client sends an HTTP GET request with these parameters in the query string:

Key Value
username squirrel
password mypassword
id 12345
format RecipeML

That is to say, the client simply visits a URL like this:

http://reciperpc.sf.net/ri?username=squirrel&password=mypassword&id=12345&format=RecipeML

3B. Server returns the "Mom's Spaghetti" recipe in RecipeML format.

Usernames and Passwords

Each method described below takes username and password parameters. These are strings with the obvious meanings and may be used by the server for authentication or ignored.

A client may, as a standard procedure, make its first call to the server with blank username and password. If fault 1, invalid username or password, is returned, the client should fetch a valid username and password (for instance, by prompting the user) and use it in future method calls to this server. If the server gives a valid response, the client may continue to use blank username and password in future method calls.

config method

struct config(username, password)

Description. Fetches configuration information about the RecipeRPC server.

Parameters. The username and password parameters have the standard types and meanings.

Return value. This struct:

Key Value type Value description
version string The version of RecipeRPC supported by this server.
description string Brief description of this server. May be used, for example, in a list of available servers.
criteria array of strings Identifiers for the criteria that can be used in searches. Examples: name, category, rating, equipment.
formats array of strings Names of the formats available from this server. Examples: RecipeML, MealMaster.

Faults. The server may return these faults:

Fault code Fault description
1 Invalid username or password.
Any value > 100 Implementation-specific faults.

search method

struct search(username, password, criteria, index)

Description. Searches for recipes matching given criteria.

Parameters. The username and password parameters have the standard types and meanings.

The criteria parameter is a struct in which:

This struct may be empty (contain no keys) which should be interpreted as a request for all recipes from the server. The server may respond with an implementation-specific fault in this case, if such queries are not allowed.

For example, the sample criteria structure above indicates that the server should return vegetarian recipes with names containing "Spaghetti".

The index parameter is an int indicating the index of the first recipe to return. That is, if this parameter is set to n and the list of all recipes matching the criteria is numbered 1, 2, 3, ..., then the server should send recipes beginning with the one numbered n. If n is greater than the number of recipes matching the criteria, then the server should return fault 3.

Normally, the client will send the value 1 for this parameter on the first call to search(). If the server sends, say, only the first 25 matching recipes in response to this call, and if the client requires more recipes, the client will normally then call search() again with index equal to 26. If still more are required, repeat with 51, 76, 101, ....

Return value. This struct:

Key Value type Value description
total int The total number of recipes that match the criteria.
recipes array An array of recipe data. See below.

The recipes element of this struct is an array, possibly empty, of structs with this form:

Key Value type Value description
name string The name of a recipe matching the given criteria.
id string An identifier that uniquely identifies this recipe to the server.

Notice that the server need not return all matching recipes, but it must return the total number of matching recipes in the member total (naturally total may be zero if nothing matches). The client can easily determine whether there are any more recipes to be had: the server has sent all the recipes if and only if

total = index + size(recipes) - 1.

The id will be used in the query string of a URL, and should therefore contain no characters that are not allowed in such a query string, such as question marks or ampersands.

Faults. The server may return these faults:

Fault code Fault description
1 Invalid username or password.
2 Invalid criterion name.
3 Index greater than total number of matching recipes.
Any value > 100 Implementation-specific faults.

Recipe request

Description. Fetches a specific recipe, using the id returned by search and specifying a format. Instead of an XML-RPC method, this is a simple HTTP GET with a query string.

Parameters. These parameters should be passed via the URL query string:
Key Value description
username Has the usual meaning.
password Has the usual meaning.
id An ID returned by the search method.
format One of the format identifiers returned by the config method.

Returned document. The server should return either:

Faults. The server may return these faults:

Fault code Fault description
1 Invalid username or password.
4 Invalid recipe identifier.
5 Invalid format.
Any value > 100 Implementation-specific faults.

Optional methods

Servers are strongly encouraged, but not required, to implement the optional introspection methods

system.listMethods()
system.methodSignature()
system.methodHelp()
These methods are described in the
XML-RPC for PHP documentation.

The text returned by each of these methods is likely to be nearly identical for each server. The reference implementation isolates these descriptions in a file, which is public domain and may be used by any implementation.

Odds and ends

The meaning of criterion values. A criterion is normally the name of a recipe attribute, such as "name" or "ingredient", and so when you specify a string value for the criterion in the search method, the server typically fetches recipes whose attribute contains that string (searching case-insensitively): hence in the example we match any recipe whose name contains "spaghetti" (searching case-insensitively).

However, the server is free to behave differently. For instance, it may search for exact matches only. Or it may interpret the value as a number and search for values greater or less than the given one. Or it may require a format, such as a-b for a range from one number a to another b. In any of these cases, the server should (but is not required to) provide and document implementation-specific fault codes (integers > 100) and detailed, helpful fault messages for invalid criterion values.

Fault descriptions. This protocol only prescribes the fault codes and their meanings; a server may return any fault string that preserves the meaning. For instance, a server may return a fault string describing the fault in a different natural language, such as German.

Order of method calls. The normal order of method calls is shown in the example above, although a real session might include multiple calls to search() (if the server does not return all matching recipes the first time) and multiple recipe requests (if more than one matching recipe is desired). However, clients are free to call any method at any time; for instance, if the identifier is known, the client can simply visit the appropriate URL using the identifier in the query string.

Copyright and disclaimer

Copyright 2004 Douglas Squirrel.

This document and translations of it may be copied and furnished to others, but not modified except as described in the next paragraph.

Derviative works of any kind whatsoever, including modified versions of this document or explanations or paraphrases of it, may be created and used in any way, so long as the word RecipeRPC is not used to identify any protocol materially different from the one described in this document. For example, you can document your own protocol based on RecipeRPC and use parts of this document in the description of your new protocol, but you can't refer to your new protocol as RecipeRPC.

While these copyright restrictions apply to the written RecipeRPC specification, no claim of ownership is made to the protocol it describes. Any party may, for commercial or non-commercial purposes, implement this protocol or any variation on it without royalty or license fee. The limited permissions granted herein are perpetual and will not be revoked.

This document and the information contained herein is provided on an "AS IS" basis and THE AUTHOR DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.


Last updated 9 February 2004
This web site copyright 2001-4 D. Squirrel
This product is RecipeML compatible.
Graphics provided by Jeff Bucchino,
the Wizard of Draws, for noncommercial use.
SourceForge.net Logo