Skip to end of metadata
Go to start of metadata

<ac:macro ac:name="unmigrated-inline-wiki-markup"><ac:plain-text-body><![CDATA[

<ac:macro ac:name="unmigrated-inline-wiki-markup"><ac:plain-text-body><![CDATA[

Zend Framework: Zend_Json_Server Component Proposal

Proposed Component Name Zend_Json_Server
Developer Notes http://framework.zend.com/wiki/display/ZFDEV/Zend_Json_Server
Proposers Matthew Weier O'Phinney
Ralph Schindler Zend Liaison
Revision 0.9 - 9 April 2008: Initial proposal
1.0 - 10 April 2008: Opening for Community Review (wiki revision: 7)

Table of Contents

1. Overview

JSON-RPC provides a standard specification for using JSON as a transmission medium for an RPC server. The only reasonable solution for Zend_Json_Server, in order to be able to interoperate as much as possible with clients and other JSON-RPC services, is to follow this specification.

Currently, there are several versions of the specification. 1.0 is widely used, and is an accepted standard. 1.1 exists in three separate proposals and has been abandoned; 1.2 has been debated heavily, and has been re-proposed as 2.0; 2.0 is close to completion, but has several important questions to answer before approval (system descriptions being one important area). This proposal will support version 1.0 initially, leaving room for support of additional versions of the specification.

While the 1.0 specification has no requirement that servers implement a system.describe method (required in the later working drafts), many clients now require that a particular JSON-RPC server have a Service Mapping Description (SMD) file to describe their service. This file reports the server version, URL, and methods in a standardized JSON format that closely follows the proposed system.describe format of later specification revisions. This proposal will address the SMD format as well.

JSON-RPC does not specify a transport. The server can be agnostic to where the request is coming from, so long as the server can assemble the information it needs to form the request. SMD can be used to indicate the transport and request method. However, if the service listens to GET requests, this adds an extra onus on the server to build the request properly based on the endpoint and the query string provided. To simplify operation of the server, and because the server will be considered a single endpoint, we will utilize only POST requests, and expect a JSON object in the raw post body.

All requests include a unique identifier so that responses can be paired with the requests asynchronously. However, JSON-RPC also has the concept of "notifications" – requests that do not require a response. Such requests are made with a null request identifier.

2. References

3. Component Requirements, Constraints, and Acceptance Criteria

  • MUST only respond to POST requests
  • MUST allow JSON-RPC Notification requests
    • SHOULD return 204 HTTP response w/o content for forward compatability
  • MUST allow retrieval of parameters from Request and Response objects
  • MUST allow retrieval of raw JSON request/response
  • MUST provide functionality to create Service Mapping Description
    • MUST implement Service Mapping Description format from json-schema group
    • MUST support optional parameters
    • MUST support default values
    • SHOULD allow specifying more parameters than signature specifies
    • SHOULD allow specifying parity of server
    • SHOULD autodetermine if requested via .smd extension
    • SHOULD have accessors for SMD metadata
    • SHOULD cache to local filesystem on request
  • SHOULD use v2.0 specifcation error codes
  • SHOULD send appropriate HTTP response headers for forward compatability
  • COULD provide functionality to facilitate JS object type hinting
  • COULD provide namespacing of classes via '-'

4. Dependencies on Other Framework Components

  • Zend_Exception
  • Zend_Server_Interface
  • Zend_Server_Reflection

5. Theory of Operation

A client would request the SMD using a .smd extension in the URL or by calling system.describe. The server would then perform introspection on the attached classes, objects, and functions to generate the SMD for the client (optionally pulling from a cache for this information).

When a client performs a JSON-RPC request, the server would determine the type of request. For a notification, it would send an immediate HTTP 204 response with no content, and buffer all additional output to ensure no additional data is sent to the client. For all other requests, it would process the request and attempt to return a JSON-RPC response.

Should an error or exception occur, the server would return an error response with the appropriate error code and error details.

6. Milestones / Tasks

  • Milestone 1: [DONE] Create this proposal
  • Milestone 2: [DONE] Solicit community feedback and incorporate
  • Milestone 3: [DONE] Create functionality to generate SMD
  • Milestone 4: [DONE] Create server, request, and response classes
  • Milestone 5: Proposal acceptance
  • Milestone 6: Write documentation

7. Class Index

  • Zend_Json_Server
  • Zend_Json_Server_Request
  • Zend_Json_Server_Response
  • Zend_Json_Server_Error
  • Zend_Json_Server_Smd
  • Zend_Json_Server_Smd_Service

8. Use Cases

UC-01

Basic Usage

UC-02

Retrieve and Store SMD

9. Class Skeletons

NOTE: Working and tested code may now be found in SVN at http://framework.zend.com/svn/framework/branch/user/matthew/zend_json_server/

Zend_Json_Server

Zend_Json_Server_Request

Zend_Json_Server_Response

Zend_Json_Server_Error

Zend_Json_Server_Smd

Zend_Json_Server_Smd_Service

]]></ac:plain-text-body></ac:macro>

]]></ac:plain-text-body></ac:macro>

Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.
  1. Jun 11, 2008

    <ac:macro ac:name="note"><ac:parameter ac:name="title">Zend Comments</ac:parameter><ac:rich-text-body>
    <p>The proposal is approved for Standard Incubator development.</p></ac:rich-text-body></ac:macro>