Sera render and purge APIs

This on-demand render API can be used to submit page URLs to SERA for rendering, allowing you to integrate with tools and automatically render frequently updated sites via scripts or tools. There is also an on-demand API for removing the rendered pages when you take out some pages from the website.

Prerequisite#

You must have an account on Nitrogen.
Your target domain on which you want to call SERA on demand api must have been registered on Nitrogen.
You must have a service account configured with Editor access. If not, you can refer this article for the same.

Render API#

An API to render pages on SERA on-demand basis

Render API Request Details#

API URL :

https://dash.n7.io/api/v2/sera/domains/{domain}/ondemand/render

Method :
```
PUT
```
Headers :
```
Authorization : Token <api-key-of-service-account>
Content-Type  : application/json
```
If using PostMan, set the Auth Type to No Auth. And then set the Authorization header in Headers section.

Payload :

{
	"pageGroupName": "Saree Category",
	"urls": [
		"https://www.example.com/saree/satin-sarees",
		"https://www.example.com/saree/shimmer-sarees",
		"https://www.example.com/saree/silk-sarees",
		"https://www.example.com/saree/supernet-sarees",
		"https://www.example.com/saree/tissue-sarees"
	]
}

These are the mandatory parameters. Please check the next section for all the available parameters.

Request Explanation#

Path params :
- domain: the domain for which urls needs to be rendered

Payload Params :

Field	Description	Mandatory	Default	Note
`urls`	List of URLs that needs to be rendered	mandatory	-	You can process a maximum of 100 URLs at a time
`pageGroupName`	Name of the page group set in Dash	optional	`Just-In-Time`	-
`viewport`	Page to be rendered for which Device viewport (Desktop/Mobile/Both)	optional	`SERA_VIEWPORT_DESKTOP_MOBILE`	`SERA_VIEWPORT_DESKTOP`, `SERA_VIEWPORT_MOBILE`, `SERA_VIEWPORT_DESKTOP_MOBILE`
`resourceBlockRegex`	List of request-url regexes that need to blocked during rendering	optional	-	eg: images and third-party calls usually not required for non-user traffic.
`pageWaitTimeout`	The time the SERA rendering process should wait before responding with timeout error	optional	`30`	-
`stabilizeWaitTimeout`	Extra time required for rendering to complete after page load	optional	`0`	-
`waitForSelector`	Process till the given selector appears on page	optional	-	-
`blockingSelectors`	List of element selectors that need to removed from the rendered page	optional	-	-
`htmlBlockingRegex`	List of element regexes that need to removed from the rendered page	optional	-	-
`callbackUrl`	A Url which will be called upon the rendering of the pages with the relevant details	optional	-	Details are given in next section

Render API Request Example#

curl --request PUT --location 'https://dash.n7.io/api/v2/sera/domains/{domain}/ondemand/render' \
--header 'Authorization: Token <api-key-of-service-account>' \
--header 'Content-Type: application/json' \
--data-raw '{
	"pageGroupName": "Sarees",
	"urls": [
		"https://www.example.com/",
		"https://www.example.com/sarees",
		"https://www.example.com/sarees/pink-silk-mayura-c1p001",
		"https://www.example.com/about-us",
		"https://www.example.com/blog",
		"https://www.example.com/blog/how-example-sarees-are-manufactured"
	],
	"viewport": "{SERA_VIEWPORT_DEVICE}",
	"resourceBlockRegex": [
		".+\\.(jpg|jpeg|png|gif|webp|avif|svg|mp3|mp4|mov|ogg|webm|wav|mpeg|woff|woff2|ttf|eot|otf)(\\?.*|&.*|$)",
		"^data:image/.+"
		"/(www.google.com/pagead|www.google.com/ccmwww.google-analytics.com|analytics.google.com|pagead2.googlesyndication.com|www.google.co.in/pagead|www.google.co.in/ads|www.facebook.com/tr|www.facebook.com/privacy_sandbox/pixel|connect.facebook.net/signals|.*.doubleclick.ne|.*.clarity.mst|.*.googleapis.com)/"
	],
	"pageWaitTimeout": 30,
	"stabilizeWaitTimeout": 10,
	"waitForSelector" : "div.userDetails p.userIdVal",
	"blockingSelectors": [
		"#sale-popup",
		"div.whatsAppFloat"
	],
	"htmlBlockingRegex": [
		"<video[^>]>([\s\S]?)</video>"
	],
	"callbackUrl" : "https://www.example.com/callbacks/sera"
}'

Render API Response Details#

Render API Response Example#

{
	"message": "905aebcc-32ed-4c77-96e9-d048276a1819"
}

Render API Response Explanation#

message : Unique UUID, to identify the URLs requested in SERA API

Render API Callback Response#

The callback URL is invoked with an HTTP POST request, containing the following payload

Render API Callback Response Details#

Method : POST
headers :
- Content-Type : application/json
- user-agent : Nitrogen/1.0 SERA Callback

Body :

{
	"runId" : "{uuid}",
	"domain" : "{domain-name}",
	"startTime" : "{timestamp}",
	"endTime" : "{timestamp}",
	"url" : "{url}",
	"statusCode" : {render-status},
	"deviceType" : "{SERA_VIEWPORT_DEVICE}"
}

Render API Callback Response Explanation#

runId : message recieved in response from SERA API,
domain : www.example.com ,
startTime : start timestamp for url processing in UTC,
endTime : end timestamp for url processing in UTC,
url : https://www.example.com/saree/satin-sarees ,
statusCode : Status code received from origin
deviceType : device type for which URL is requested

Render API Callback Response Example#

{
	"runId" : "905aebcc-32ed-4c77-96e9-d048276a1819",
	"domain" : "www.example.com",
	"startTime" : "2024-10-15T08:31:26.857Z",
	"endTime" : "2024-10-15T08:31:52.182Z",
	"url" : "https://www.example.com/saree/satin",
	"statusCode" : 200,
	"deviceType" : "desktop"
}

Delete Render Storage API#

An API to delete the pages rendered at SERA end

Delete Render Storage API Request Details#

API URL :

https://dash.n7.io/api/v2/nda/delivery/domains/{domain}/sera/purge-render

Method :
```
PUT
```
Headers :
```
Authorization: Token <api-key-of-service-account>
Content-Type: application/json
```
If using PostMan, set the Auth Type to No Auth. And then set the Authorization header in Headers section.

Payload :

{
	"url": "https://www.example.com/saree/satin-sarees"
}

Delete Render Storage API Request Explanation#

Path params :
- domain: the domain for which the rendered page needs to be deleted
Payload Params :
- Field Description Mandatory Note
  url The full URL of the page whose rendered storage needs to be deleted mandatory Must be a valid URI

Field	Description	Mandatory	Note
`url`	The full URL of the page whose rendered storage needs to be deleted	mandatory	Must be a valid URI

Delete Render Storage API Request Example#

curl --request PUT --location 'https://dash.n7.io/api/v2/nda/delivery/domains/www.example.com/sera/delete-storage' \
--header 'Authorization: Token <api-key-of-service-account>' \
--header 'Content-Type: application/json' \
--data-raw '{
	"url": "https://www.example.com/saree/satin-sarees"
}'