Functions

From The Socknet

The Socknet operates when providers and services make HTTP requests to each other using URL's built from Provider URL's and API URL's.

Contents 1 Calling 2 How to Read Function Specifications 3 Reserved Fields 3.1 Request Fields 3.1.1 from 3.1.2 to 3.1.3 return 3.1.4 pagination 3.2 Response Fields 3.2.1 error 3.2.2 request 3.2.3 redirect 3.2.4 accepted 3.2.5 cache_time 3.2.6 pending 3.2.7 pagination 3.2.8 results 3.3 Response "Types" 3.3.1 accept 3.3.2 redirect 4 Pagination 5 How do I get the HTTP request body in MY language? 6 Considerations 7 See Also

Calling

A function is called by appending the function's name to the user's Provider URL to produce a Function URL.

Example:

 
User's provider: "http://www.provider.com/UserA/"

Function name: "prindle_flax"

Function URL: "http://www.provider.com/UserA/prindle_flax"

URL components should be encoded, so the URL to function "hello:world" would be http://www.provider.com/UserA/hello%3Aworld.

Once the Function URL is built the function is called by making an an HTTP GET or POST to that URL.

A function's specification indicates whether it should receive a GET or a POST.

A function which receives a GET accepts no data.

A function which receives a POST must have a Content-type header with a value of "application/json" and an HTTP request body containing a JSON object.

A function responds with a JSON object or nothing according to its specification.

How to Read Function Specifications

In this documentation we use a specific notation for function examples (and examples often serve as specifications as well).

<POST|GET> function-name
JSON object

This example explains a call to the get_message function:

POST get_message
{ from: { openid: "http://users-openid.com/" }
  guid: {
    openid: "http://friend.com/",
    id: "100"
  }
}

This is not a literal example of the bytes that should be sent. It indicates that, in order to call the function, an HTTP POST should be issued to the URL of the get_message function and that the HTTP body must have a JSON object matching the structure shown. (Although JSON requires object keys to be quoted, our examples usually leave them out for readability. But you'll be using a JSON library, so you have nothing to worry about.)

The notation for responses is similar:

->
{ message: "I just got a root canal!"
  replies_accepted: true
  created: "Sun, 06 Nov 1994 08:49:37 GMT"
}

The symbol -> indicates that this is a response.

Reserved Fields

Request Fields

Several fields of the POST object are reserved for specific uses. Function specifications MAY NOT override these uses:

from

Contains an object describing the entity that sent the request.

{ ...
  from: { openid: "http://openid.com/UserA" },
  ...
}

{ ...
  from: { serviceid: "http://myblog.com/server" }
  ...
}

to

Contains an object describing the entity that should be receiving the request.

{ ...
  to: { openid: "http://openid.com/UserA" }
  ...
}

return

Contains a URL in a string. This field indicates that the requesting agent will accept a redirect response. After a redirect, the user will be sent back to the URL given in the return field.

{ ...
  return: "http://service.com/the-page-the/user-should-go/to-next",
  ...
}

pagination

Contains an object with the fields page and results_per_page. This is used on functions which indicate that they require pagination. The results of such a call will have at a minimum a pagination field and a results field, unless an error occurs.

The field page must be an integer greater than or equal to 1.

The field results_per_page must be an integer greater than or equal to 1.

Response Fields

Some fields are reserved for particular uses in responses:

error

Indicates that an error occurred. See Success and Failure.

request

A copy of the object sent in the request or, in the case of a GET, an object describing whatever defaults were used to produce the output. Example can be found in Finding Messages.

redirect

If present, the requester must redirect the user to this URL in order to continue. The presence of this field indicates that the user must be consulted before the function can be run.

This field is only included in a response to a POST. The requester is free to ignore the redirect if it prefers to cancel the operation. No further action is necessary.

This field should only be included if the request included a return field. If a redirect is required, but no return field was given, the function will usually respond with an error (which isn't a bad thing at all).

If there is no user or the user is not the owner of the information being queried, then there is no reason to redirect him. See Message Notification for an example.

accepted

A boolean indicating that some posted information was accepted as in Message Notification. If a response has a true accepted field, then it must have no redirect field.

cache_time

The number of minutes that the response may be cached for.

pending

A boolean used to indicate that the receiver will consider the request and respond via a separate call.

pagination

Used on functions which indicate that they require pagination because the results can be very large.

Contains an object with the fields page, results_per_page, page_count and results_count.

The fields page and results_per_page should be the same as given in the pagination field of the request. However, if the pagination field of the request was absent or had bad data, these fields will hold the data that the responder actually used to create the response.

The field page_count contains the maximum acceptable value for page.

The field results_count contains the number of total results available.

If this field is present, the field results should also be present.

results

Holds the results of a call to a paginated function. The function specification indicates what is in this field. It is generally an object or an array.

Response "Types"

Responses can be categorized by the generalized fields they include.

accept

A response that has an accepted field, whether the field is true or false.

redirect

A response that has a redirect field.

Pagination

Some functions, such as friends, can produce so much data that they are paginated. A "paginated function" is a function which accepts the pagination field in its request and has pagination and results fields in its response. The results field holds the relevant data, and the pagination fields hold information about what "page" of data is being accessed.

POST friends
{ pagination: {
                page: 1,
                results_per_page: 200
              }
}

->

{ pagination: {
                page: 1,
                results_per_page: 200,
                results_count: 423,
                page_count: 1
              },
  results: {
             ... 200 friends objects ...
           }
}

If the pagination field is not present in the request, the entity receiving the request fills in with default data. The receiving entity may also choose to change the values given in the request. In these cases, the new values are indicated in the response.

How do I get the HTTP request body in MY language?

How do I get the HTTP request body in MY language?

Considerations

Don't confuse HTTP POSTs with the more general sense of the term post (as in, posting to a forum or blog) or Direct Posting.

The official functions set out in this documentation do not have special characters and so require no special encoding. However, extended functions may have such characters. So encode and expect encoding. Don't forget, you library writers.

See Also

• ReadMe
• Provider URL
• Functions
• IP Verification
• Friends
• Services