# API endpoints
MarfeelPress offers several endpoints to extract resources from the tenant's site by using the official WordPress REST API (opens new window), more precisely by the usage of routes (opens new window).
A route is the “name” you use to access endpoints, used in the URL. A route can have multiple endpoints associated with it, and which is used depends on the HTTP verb. For example, with the URL
http://example.com/wp-json/wp/v2/posts/123:
- The "route" is
wp/v2/posts/123- The route doesn't includewp-jsonbecausewp-jsonis the base path for the API itself.- This route has 3 endpoints:
GETtriggers aget_itemmethod, returning the post data to the client.PUTtriggers anupdate_itemmethod, taking the data to update, and returning the updated post data.DELETEtriggers adelete_itemmethod, returning the now-deleted post data to the client.
There are three routes configured in MarfeelPress plugin that allow resource extraction.
- Extractor, for articles extraction
- Ripper, for sections extraction
- Widgets, for widget information extraction
format
The response of those routes is always a JSON object containing the requested content.
# Extractor
The extractor route provides all the information about a specific article, such as the title, excerpt, author, date, article body...
The output data is processed by BoilerpipePressExtractor which returns an HTML for BoilerpipeExtractor to produce the final HTML.
Missing content
The API response doesn't contain information other plugins may add to the articles, such as Co-Authors Plus (opens new window), which adds information about the article author.
This can be validated by comparing the response of the extractor route to the HTML of the article.
Route: marfeelpress/v1/extractor/
Endpoint: GET
Query params: URL
Example:
- rest_route parameter
https://www.tenant.com/?rest_route=/marfeelpress/v1/extractor&url=/article-with-a-slug/
- /wp-json/
https://www.tenant.com/wp-json/marfeelpress/v1/extractor?url=/article-with-a-slug/
Click to see how a response looks like:
{
"id": 69290,
"uri": "https:\/\/www.example.com\/news-article-url\/",
"title": "Article title",
"subtitle": null,
"excerpt": "excerpt text",
"author": {
"name": "Author name",
"url": "https:\/\/www.example.com\/author\/author-page\/",
"avatar": "https:\/\/secure.gravatar.com\/avatar\/image",
"description": "author description"
},
"media": {
"alt": "",
"caption": "",
"imageRatio": 0.50735,
"src": "https:\/\/i1.wp.com\/www.example.com\/wp-content\/uploads\/article-main-image.png",
"width": 680,
"height": 345
},
"date": "",
"firstPage": null,
"pages": null,
"categories": [
{
"id": "14",
"name": "Category name",
"content": "https:\/\/www.example.com\/category\/",
"parent": null
}
],
"detailItem": {
"id": 69290,
"kicker": null,
"body": "Article body in HTML",
"numberOfWords": 0,
"readingTime": 0,
"summary": "article summary",
"advertisement": "ALL",
"commentingSystem": null,
"tagInformation": {
"html": "<meta name=\"tag.name\" content=\"\" \/>...",
"tagList": [
{
"name": "META",
"attributes": {
"name": "geo.placename",
"content": ""
}
},
{
"name": "META",
"attributes": {
"name": "geo.position",
"content": ";"
}
},
{
"name": "META",
"attributes": {
"name": "geo.region",
"content": ""
}
},
{
"name": "META",
"attributes": {
"name": "robots",
"content": "index, follow"
}
},
{
"name": "META",
"attributes": {
"name": "googlebot",
"content": "index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1"
}
},
.
.
.
{
"name": "TITLE",
"content": "article title"
}
]
},
"structuredData": null,
"metadatas": null,
"pocket": {
"tags": [
{
"name": "Tag name",
"content": "https:\/\/www.tenant.com\/tag\/tag-name\/"
}
]
}
},
"isExtractable": true,
"pocket": {
"categories": [
"category-name"
]
}
}
# Ripper
The ripper route provides all the necessary information to render a section in the Marfeelized version. This route requires a Layout Descriptor to be sent via POST to build the section correctly.
TIP
Layout Descriptor contains information about how many articles should appear in the section, where are those articles extracted from, content group settings, the layout of each article and content group...
When Layout Descriptor is not properly configured, this route will fail to respond with the expected result.
Post type
When the response is empty it may be due to incompatible Post Types (opens new window) configuration. Check the Post Types configuration in the MarfeelPress plugin settings page.
Route: marfeelpress/v1/ripper/
Endpoint: POST
Query params: URL
Example:
rest_routeparameterhttps://www.tenant.com/?rest_route=/marfeelpress/v1/ripper&url=/section-path/
/wp-json/https://www.tenant.com/wp-json/marfeelpress/v1/ripper?url=/section-path/
Click to see how a response looks like:
{
"logs": null,
"items": [
{
"id": 69381,
"uri": "https:\/\/www.example.com\/news\/article-example-url\/",
"title": "First article title",
"subtitle": null,
"excerpt": "article excerpt",
"author": {
"name": "Author name",
"url": "https:\/\/www.example.com\/author\/author-page\/",
"avatar": "https:\/\/secure.gravatar.com\/avatar\/image",
"description": ""
},
"media": {
"alt": "",
"caption": "",
"imageRatio": 0.5627198124267291934330614822101779282093048095703125,
"src": "https:\/\/i2.wp.com\/www.example.com\/wp-content\/uploads\/media-image.jpg",
"width": 1706,
"height": 960
},
"date": "",
"firstPage": null,
"pages": null,
"detailItem": null,
"isExtractable": true,
"pocket": {
"categories": [
"category"
]
}
},
{
"id": 69378,
"uri": "https:\/\/www.example.com\/home\/example-article-url\/",
"title": "Second article title",
"subtitle": null,
"excerpt": "article excerpt",
"author": {
"name": "Author name",
"url": "https:\/\/www.example.com\/author\/author-page\/",
"avatar": "https:\/\/secure.gravatar.com\/avatar\/image",
"description": ""
},
"media": {
"alt": "",
"caption": "",
"imageRatio": 0.5627198124267291934330614822101779282093048095703125,
"src": "https:\/\/i2.wp.com\/www.example.com\/wp-content\/uploads\/article-media.jpg",
"width": 1706,
"height": 960
},
"date": "",
"firstPage": null,
"pages": null,
"detailItem": null,
"isExtractable": true,
"pocket": {
"categories": [
"Economia"
]
}
},
.
.
.
],
"tagInformation": {
"html": "<meta name=\"tag.name\" content=\"\" \/>...",
"tagList": [
"tagList": [
{
"name": "META",
"attributes": {
"name": "geo.placename",
"content": ""
}
},
{
"name": "META",
"attributes": {
"name": "geo.position",
"content": ";"
}
},
{
"name": "META",
"attributes": {
"name": "geo.region",
"content": ""
}
},
{
"name": "META",
"attributes": {
"name": "robots",
"content": "index, follow"
}
},
{
"name": "META",
"attributes": {
"name": "googlebot",
"content": "index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1"
}
},
.
.
.
{
"name": "TITLE",
"content": "article title"
}
]
},
"metadata": null
}
# Widgets
The widgets route provides the information related to widgets required for their implementation in Marfeel via rawHTML.
Route: marfeelpress/v1/widgets
Endpoint: GET
Query params: token
Example:
rest_routeparameterhttps://www.tenant.com/?rest_route=/marfeelpress/v1/widgets&token=XXXXXXXXXXXXXXXX
/wp-json/https://www.tenant.com/wp-json/marfeelpress/v1/widgets?token=XXXXXXXXXXXXXXXX
Click to see how a response looks like:
{
"footer-widget": {
"widgets": [
{
"id": "nav_menu-3",
"name": "Navigation Menu",
"class": "WP_Nav_Menu_Widget",
"option_name": "widget_nav_menu",
"html": "<div class=\"widget widget_nav_menu\"><h2 class=\"widgettitle\">WidgetHTML</div></div>"
},
{
"id": "nav_menu-4",
"name": "Navigation Menu",
"class": "WP_Nav_Menu_Widget",
"option_name": "widget_nav_menu",
"html": "<div class=\"widget widget_nav_menu\"><h2 class=\"widgettitle\">WidgetHTML</div></div>"
},
{
"id": "nav_menu-5",
"name": "Navigation Menu",
"class": "WP_Nav_Menu_Widget",
"option_name": "widget_nav_menu",
"html": "<div class=\"widget widget_nav_menu\"><h2 class=\"widgettitle\">WidgetHTML</div></div>"
}
],
"name": "Default Sidebar"
},
"sidebar-offcanvas": {
"widgets": [
{
"id": "nav_menu-2",
"name": "Navigation Menu",
"class": "WP_Nav_Menu_Widget",
"option_name": "widget_nav_menu",
"html": "<div class=\"widget widget_nav_menu\"><h2 class=\"widgettitle\">WidgetHTML</div></div>"
}
],
"name": "Off-Canvas"
},
"sidebar-hero": {
"widgets": [],
"name": "Hero"
},
"sidebar-loaded": {
"widgets": [],
"name": "Auto Loaded Sidebar"
}
}
# Availability
The availability route provides the current Marfeel activation status.
Route: marfeelpress/v1/plugin/availability
Endpoint: GET
Example:
rest_routeparameterhttps://www.tenant.com/?rest_route=/marfeelpress/v1/plugin/availability
/wp-json/https://www.tenant.com/wp-json/marfeelpress/v1/plugin/availability
Response example:
{
"availability": "ALL"
}