Zapp apps consume data via Pipes2 Endpoints.
A Pipes2 Endpoint is a simple REST API that responds with a JSON that conforms to the Pipes Feed JSON schema. Pipes2 Endpoints can be developed in any programming language or framework.
A good implementation of Pipes2 Endpoints will result in consumer applications that are secure & efficient as well as increase the flexibility available for editors working in Zapp Studio.
Users of Zapp Studio can connect UI components to any Pipes2 Endpoint, the Pipes2 Client embedded in Zapp's applications will send the endpoint additional context about the request such as user/device-specific properties.
A Pipes2 Endpoint can be implemented as a middleware between the consumer applications and the backend system (i.e. CMS) or as an integral part of the backend system, for example as a wordpress plugin. When deciding about these options it's best to take into account the requirements regarding latency, scale and cost. It's often the case that legacy CMSs does not meet the scalability needed by consumer applications, for those cases Applicaster recommends to implement the Pipes2 Endpoints as a middleware on a layer that is more cost-effective to scale (for example serverless) and ensure the calls to the legacy system's API are cached.
Pipes2 Simple Endpoint Example
Using the Path and Query Parameters
When a Pipes2 Client is instructed to fetch a feed from a given URL, the client will attempt to find a configured Pipes2 Endpoint from Zapp's data source configuration with an endpoint URL that is a prefix of the feed URL.
This means that implementations may choose to implement one endpoint for all types of data and rely on the path and query string to control the returned entries. The possible paths and query parameters are not governed by Zapp or the Pipes2 protocol except the
ctx query parameter that is reserved for protocol usage.
For example, given an endpoint with the prefix of
https://example.com/pipes2, a component can fetch data using the feed URL
https://example.com/pipes2/shows?page=1&limit=25 or by using
The following expressjs code uses both path and parameters to return the wanted result:
Using Context Parameters
Pipes2 Clients can send additional parameters to the Pipes2 Endpoint when instructed to do so. When an endpoint is configured for an application in Zapp it is configured with a list of local context parameters to be sent for the endpoint (Context Keys).
These parameters will be sent to the endpoint in the
ctx query string parameter.
The value of
ctx will be a
base64URL encoded JSON containing an object whose keys are the Context Keys and their respective values in the application's context are the values.
To find out more about
base64URLplease refer to https://tools.ietf.org/html/rfc4648#section-5
Context parameters are provided by the Zapp SDK and the plugins that are activated in the application. See list of builtin context parameters
For example, an endpoint that uses the
deviceId context parameter to customize the feed:
Geo Restricting content with
signedDeviceInfoToken context key
A common use case is to be able serve / geo block specific content according to the user's location.
Zapp apps support this feature out of the box using
Once you set in Zapp the the
signedDeviceInfoToken context key to an Endpoint - a signed JWT context key will be added to each of the feeds' endpoints.
On your Pipes2 server implementation you'll be able to decode / validate the JWT token and use it to serve the right content to your user.
If you want to test your server implementation, you can use the Pipes2 Feed JSON validator :
- Add you feed URL in the URL section.
- Click on the
Add context key & value pairlink.
- Add the context key
- Go to
https://di.applicaster.com/and copy the value of the
jwtkey and paste it in the as the value of the context key.
- Click on the
Analyzebutton - you'll be able to see the feed geo targeted to your location.
- In the case you need to test another location access the
https://di.applicaster.com/from a VPN to simulate your desired country.