ezjscore server functions for your app #

This page is for app developers who need an endpoint that does not exist yet, for example one call that gives a home screen everything it shows. It explains what to ask a PHP developer for and how the app calls the result. The server-side how-to is JSON endpoints with ezjscore.

Contents #

1. When to ask for one
2. What gets built
3. Calling it
4. Authentication from a native app
5. A brief for the PHP developer

When to ask for one #

What gets built #

A server function is a public static PHP method registered in an [ezjscServer_<name>] block of an extension's ezjscore.ini.append.php. The router refuses any name without such a block, calls <class>::<function>( array $args ) and wraps the return value (How a call works). If the extension writes it as an expservices domain instead (a class extending expServiceBase), it gets the envelope, the catalog entry and API tokens for free (A service domain of your own).

Calling it #

curl -s 'https://example.com/ezjscore/call/<name>::<function>::<argument>?ContentType=json'

{"error_text": "", "content": {"...": "the function's return value"}}

A plain server function answers its own value in content; an expservices domain answers the {"ok":...} envelope inside content (Calling expservices from an app). Check error_text first: it is set when the router refused the call.

ezjscore ships a test function you can use to check the interface: ezjsc::time.

Authentication from a native app #

A plain server function runs as the current user of the request: a session cookie, or anonymous. It does not understand REST keys, OAuth tokens or expservices tokens by itself. For an app that is a reason to prefer an expservices domain, which accepts expservices tokens, or a REST provider, which uses the REST authentication.

Classic server functions can also be guarded by the policy ezjscore/call with the FunctionList limitation; how strictly is set by RequirePolicy (not set, disabled or enabled) in the function's block (expservices reference: access).

A brief for the PHP developer #

• The screen and the exact JSON it needs (an example answer).
• The user the call runs as, and which content that user may read.
• Read or write; writes are POST only, with the form token for sessions or a bearer token for expservices.
• Paging: limit and offset as the last arguments.
• Error cases and how the app should see them.
• Caching: how fresh the answer must be.
• "Check permissions in every function; validate and cast every argument; return data, not HTML" are the rules of JSON endpoints with ezjscore: security.

Related pages #

• Which API for your app
• Remote services with expservices
• REST and JSON calls (cookbook)
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.