I have a handful of WordPress websites that use The Events Calendar for displaying events that are open to the public.
I notice if I type a cities name and then the word event, that our website is not being pulled in to the special section that appear. Google uses its Knowledge Graph. I was looking through the source code and noticed that our sites uses JSON-LD, generated from the information used for the event, one of the methods Google talks about using, but don’t understand why our site information isn’t being shown.
These sites have been up a year and get 3k visits a month so they're being indexed fairly regularly.
I was looking through the event properties JSON-LD, and I noticed the entire event address (street, city, state zip) gets put inside the name property of the Place or Postal array (Heres a screenshot of my sites schema). When I look up other events that are pulled into Google, they list the those attributes in the address properties (Screenshot of other site’s schema).
I think because the address is put into the name property instead of the address property, that Google might not be showing the events. Has anybody else seen this happen with their sites? Or is something else wrong with the sites we set up?
Right now your events are marked up using the Google example, but I believe this is wrong:
https://developers.google.com/structured-data/rich-snippets/events
"location" : {
"#type" : "Place",
"sameAs" : "http://www.hi-dive.com",
"name" : "The Hi-Dive",
"address" : "7 S. Broadway, Denver, CO 80209"
}
2019 edit: The markup and URL above have since changed and match what is expected from the testing tool.
In order for your sites structured data to match that other event you have a screen shot of, you will need to adjust your JSON-LD to the way it's presented on schema.org, which uses PostalAddress and narrows down a little bit more:
https://schema.org/location (and https://schema.org/PostalAddress) - Click the JSON-LD example tabs
"location": {
"#type": "Place",
"name": "Withworth Institute",
"address": {
"#type": "PostalAddress",
"addressLocality": "Seattle",
"addressRegion": "WA",
"postalCode": "98052",
"streetAddress": "20341 Whitworth Institute 405 N. Whitworth"
},
"url": "wells-fargo-center.html"
}
I can't say for certain if this is the primary reason for your issue but I do think you should follow the schema.org approach either way. Even the Structured Data Tool per your screenshots seems to indicate that it's looking for postalAddress even though Google doesn't use that in the example.. perhaps that article is outdated.
I can confirm that a migration to JSON-LD from inline RDFa style schema, which validates 100% using their new rich snippet validator tool no longer shows Review stars in search results. They've also taken away the ability to see stars validate using old style RDFa schema validation.
This could be an issue with the search team not talking to the developers responsible for the structured data and schema tools, rolling out disjointed feature upgrades. Their recommended use of JSON-LD will likely have a negative impact on display in search in the near term if you'd like to see additional meta data populate in search results pages.
If meta data in search results is a firm requirement you could roll off your JSON-LD module and use a module with the older RDFa or microdata implementation inline in your HTML. Hopefully this will be remedied soon.
Related
I've come to the conclusion that building a truly RESTful API, one the uses HATEOAS is next to impossible.
Every content I've come across either fails to illustrate the true power of HATEOAS
or simply does not explicitly mentions the inherent pain points with the dynamic nature of HATEOAS.
What I believe HATEOAS is all about:
From my understanding, a truly HATEOAS API should have ALL the information needed to interact with the API, and while that is possible, it is a nightmare to use especially with different stacks.
For example, consider a collection of resources located at "/books":
{
"items": [
{
"self": "/book/sdgr345",
"id": "sdgr345",
"name": "Building a RESTful API - The unspoken truth",
"author": "Elad Chen ;)",
"published": 1607606637049000
}
],
// This describes every field needed to create a new book
// just like HyperText Markup Language (i.e. HTML) rendered on the server does with forms
"create-form": {
"href": "/books",
"method": "POST",
"rel": ["create-form"],
"accept": ["application/x-www-form-urlencoded"],
"fields": [
{ "name": "name", "label": "Name", "type": "text", "max-length": "255", "required": true }
{ "name": "author", "label": "Author", "type": "text", "max-length": "255", "required": true }
{ "name": "author", "label": "Publish Date", "type": "date", "format": "dd/mm/YY", "required": true }
]
}
}
Giving the above response, a client (such as a web app) can use the "create-form" property to render an actual HTML form.
What value do we get from all this work?
The same value we've been getting from HTML for years.
Think about it, this is exactly what hypertext is all about, and what HTML has been designed for.
When a browser hits "www.pizza.com" the browser has no knowledge of the other paths that a user
can visit, it does not concatenate strings to produce a link to the order page -> "www.pizza.com/order", it simply renders anchors
and navigates when a user clicks them. This is what allows web developers to change the path from "/order" to "/shut-up-and-take-my-money" without changing any client (browsers).
The above idea is also true for forms, browsers do not guess the parameters needed to order a pizza, they simply render a form and its inputs, and handle its submission.
I have seen too many lines of codes in front-ends and back-ends alike, that build strings
like -> "https://api.com" + "/order" - You don't see browsers do that, right?
The problems with HATEOAS
Giving the above example ("/books" response), in order to create a new book, clients are expected to parse the response in order to leverage the true power of this RESTful API, otherwise, they risk assuming what the names of the fields are, which of them is required, what their expected type is, etc...
Now consider having two clients within your company that are using this API,
one for the web (browsers) written in JS, and another for the mobile (say an android app) written in Java. They can be published as SDK's, hopefully making 3 party consumers have an easier integration.
As soon as the API is used by clients outside your control, say a 3rd party developer with an affinity to python, with the purpose of creating a new book.
That developer is REQUIRED to parse such a response, to figure out what the parameters are, their name, the URL to send inputs to, and so on.
In all my years of developing I have yet to come across an API such as the one I have in mind.
I have a feeling this type of API is nothing more than a pipe dream, and I was hoping to understand whether my assumptions are correct, and what downfalls it brings before starting the implementation phase.
P.S
in case it's not clear, this is exactly what HATEOAS compliant API is all about - when the fields to create a book change clients adapt without breaking.
On the Hypermedia Maturity Model (HMM), the example you give is at Level 0. At this level, you are absolutely correct about the problems with this approach. It's a lot of work and developers are probably going to ignore it and hard-code things anyway. However, with a generic hypermedia enabled media type, not only does all that extra work go away, it actually reduces the work for developers.
Let's take a step back for a moment and consider how the web works. There are three main components: the web server, the web browser, and the driver (usually a human user). The web server provides HTML, which the web browser executes to present a graphical user interface, which the driver can use to follow links and fill out forms. The browser uses the HTML to completely abstract from the driver all the details about how to present the form and how to send it over HTTP.
In the API world, this concept of the generic browser that abstracts away the media type and HTTP details hasn't taken hold yet. The only one I know about that is both active and high quality is Ketting. Using a browser like Ketting, removes all of that extra work the developer would have to put into making use of all that hypermedia. A hypermedia browser is like an SDK that API vendors often provide except that it works for any API. In theory, you can link from one API to another completely unrelated API. APIs would no longer be islands, they would become a web.
The thing that makes hypermedia browsers possible are general purpose hypermedia enabled media types. HTML is of course the most successful and famous example, but there are JSON based media types as well. Some of the more widely used examples are HAL and Siren.
The higher level a media type is on the Hypermedia Maturity Model, the more that a generic browser can do to abstract way the media-type, URIs, and HTTP details. Here's a brief explanation. Checkout the blog post linked above for more details and examples.
Level 0: At this level, hypermedia is encoded in an ad-hoc way. A browser can't do much with this because every API might encode things a little different. At best a browser can use heuristics or AI to guess that something is a link or a form and treat it as such, but generally HMM Level 0 media-types are intended for developers to read an interpret. This leads to many of the challenges you identified your question. Examples: JSON and XML.
Level 1: At this level, links are a first class feature. The media type has a well defined way to represent a link. A browser knows unambiguously what is to be interpreted as a link and can provide an interface to follow that link without the user needing to be concerned about URI or HTTP. This is sufficient for read-only APIs, but if we need the user to provide input, we don't have a way to represent a form-like hypermedia control. It's up to a human to read the documentation or an ad-hoc form representation to know how to submit data. Examples: HAL, RESTful JSON.
Level 2: At this level, forms (or form-like controls) are a first class feature. A media type has a well defined way of representing a form-like hypermedia control. A browser can use this media type to do things like build an HTML Form, validate user input, encode user input into an acceptable media type, and make an HTTP request using the appropriate HTTP method. Let's say you want to change your API to support PATCH and you prefer that application start using it over PUT. If you are using a HMM Level 2 media type, you can change method in the representation and any application that uses a hypermedia browser that knows how to construct a PATCH request will start sending PATCHs instead of PUTs without any developer intervention. Without a HMM Level 2 media type, you're stuck with those PUTs until you can get all the applications that use your API to update their code. Examples: HTML, HAL-Forms, Siren, JSON Hyper-Schema, Uber, Mason, Collection+JSON.
Level 3: At this level, in addition to hypermedia controls, data are also self-describing. Remember those three main components I mentioned? The last one, "driver", is the major difference between using hypermedia on the web and using hypermedia in an API. On the web, the driver is a human (excluding crawlers for simplicity), but with an API, the driver is an application. Humans can interpret the meaning of what they are presented with and deal with changes. Applications may act on heuristics or even AI, but usually they are following a fixed routine. If something changes about the data that the application didn't expect, the application breaks. At this level, we apply semantics to the data using something like JSON-LD. This allows us to construct drivers that are better at dealing with change and can even make decisions without human intervention. Examples: Hydra.
I think the only downside to choosing to use hypermedia in your API is that there aren't production-ready HMM Level 2 hypermedia browsers available in most languages. But, the good news is that one implementation will cover any API that uses a media type it supports. Ketting will work for any API and application that is written in JavaScript. It would only take a few more similar implementations to cover all the major languages and choosing to use hypermedia would be an easy choice.
The other reason to choose hypermedia is that it helps with the API design process. I personally use JSON Hyper-Schema to rapid-prototype APIs and use a generic web client to click through links and forms to get a feel for API workflows. Even if no one else uses the schemas, for me, it's worth having even if just for the design phase.
Implementing a HATEOAS API needs to be done both on the server and on the clients, so this point you make in the comments is very valid indeed:
changing a resource URI is risky given I don't believe clients actually "navigate" the API
Besides the World Wide Web, which is the best implementation of HATEOAS, I only know of the SunCloud API on the now decommissioned Project Kenai. Most APIs out there don't quite make use of HATEOAS, but are just a bunch of documented URLs where you can get or submit specific resources (basically, instead of being "hypermedia driven", they are "documentation driven"). With this type of API, clients don't actually navigate the API, they concatenate strings to go at specific endpoints where they know they can find specific resources.
If you expose a HATEOAS API, developers of any clients can still look at the links you return and may decide to build them on their own 'cause they figure what the API is doing, so then think they can just bypass any other navigation that might be needed and go straight for the URL, because it is always /products/categories/123, until - of course - it isn't anymore.
A HATEOAS API is more difficult to build and adds complexity to both the server and the clients, so when deciding to build one, the questions are:
do you need the flexibility HATEOAS is giving you to justify the extra complexity of the implementation?
do you want to make it easier or harder for clients to consume your API?
does the knowledge and discipline to make it all work exist on both sides (server developers and clients developers)?
Most of the times, the answer is no. In addition, many times the questions don't even get asked, instead people end up with the approach that is more familiar because they've seen the sort of APIs people build, have used some, or built some before. Also, many times, a REST API is just stuck in front of a database and doesn't do much but expose data from the database as JSON or XML, so not that much need for navigation there.
There is no one forcing you to implement HATEOAS in your API, and no one preventing you to do so either. At the end of the day, it's a matter of deciding if you want to expose your API this way or not (another example would be, do you expose your resources as JSON, XML, or let the client chose the content type?).
In the end, there is always the chance of breaking your clients when you make changes to your API (HATEOAS or no HATEOAS), because you don't control your clients and you can't control how knowledgeable the client developer are, how disciplined, or how good of a work they do in implementing someone else's API.
I am creating a hypermedia api that conforms to the HAL spec
When a user submits a payment they need to specify what type of card they are using (Visa, Master Card etc)
So for a particular field that is submitted there is a specific list of values that can be used
How do I present that pick list to the user?
As embedded data?
Is there generally a way to associate a field with a given set of data?
I realise the HAL spec is very small and doesnt cover this issue specifically. But in general hypermedia apis how do people usually present this data?
Or should I simply explain the field in the CURIE link?
thanks
You are right, HAL does not specifically cover this issue. You can solve this by essentially copying HTML. There are different widgets defined in HTML to present stuff, for example a combobox with listed options.
You can define a media-type that has similar controls in it, and you can define the processing model for the media-type as well. It can be a json representation of course, does not need to be xml.
For example
{
...
"cardType": {
"inputType": "select",
"possibleValues": ["Visa", "MasterCard", ... ]
}
...
}
There is no ready-made format that I know of unfortunately.
Let's assume that I have a resource called group with the following representation:
{
"id": 1,
"name": "Superheroes"
"_links": {
"self": {
"href": "http://my.api.com/groups/1"
}
}
}
Now let's say I want to create a new person instance by POSTing to /persons/1. Which of the following should I use for the request body:
Using ID
{
"name": "Batman",
"groupId": 1
}
Using link
{
"name": "Batman",
"group": "http://my.api.com/groups/1"
}
With the first method I access the id directly either to look up the related resource or eventually store the id in the database, when I persist the person instance. But with the other method, I either have to extract the id from the URI or, follow the link to load the related resource, and then find out its id. I really don't want to store the URI in the database.
With the latter option, seeing that the server controls the structure of the URI, is it fine for me to parse the id out of the link? Following the link back to the server itself seems odd, seeing that at this point we already have access to the information directly (we just need the id).
So to sum up, which of these options is best?
Use the id directly.
Use the link, but parse out the id.
Use the link, but access the link to get the resource instance, and then get the id.
TL;DR: Use simple ids.
More detailed explanation:
A straightforward approach is to create a person by POSTing to /groups/1/persons with a payload {"name": "Batman"}.
However, while such approach works for simple cases, the situation gets complicated if there are 2 resources that need to be referenced. Let's assume that a person also needs to belong to exactly one company:
GET /persons/1
{
"name": "Batman",
"group": 1, // Superheros, available at /groups/1
"company": 5 // Wayne Enterprises, available at /companies/5
}
Since there is no relationship between companies and groups, it is not semantically correct to create a person via POSTing to /groups/1/companies/5/persons or to /companies/5/groups/1/persons.
So let's assume you want to create a person with a request looking like this:
POST /persons
{
"name": "Batman"
"group": ???, // <--- What to put here?
"company": ??? // <--- What to put here?
}
Which brings us to the answer to your question:
Ease of use. Your API should be primarily designed for the ease of use. This is especially true, if you design a public API. Therefore, Option 2 (Use the link, but parse out the id) is out, since it imposes additional work for clients of your API.
Constructing search queries. If you want to be able to query persons which belong to the company 10 and the group 42, simple ids lead to more readable and less error-prone urls. Which of the following do you consider more readable?
URL with a simple id:
GET /groups/42?company=10
or URL with a url-encoded link:
GET /groups/42?company=http%3A%2F%2Fmy.api.com%2Fcompanies%2F10
I wouldn't underestimate the point of readability. How many times do you need to debug your API in various curls, logs, postmans, etc.
Development Links need to be parsed in the backend, while simple ids can be used directly. It's not about performance, but rather about additional work/tests you have to put in.
Endpoint maintenance. Imagine that your API endpoint evolves. You decide one day to switch to https or to include versioning in the url. This might break API clients, if they for some reason rely on structure of the links. Also, you might want to checkout if link parsing on your backend is done properly.
Argumentum ab auctoritate I know this is not a proper argument, but if you checkout APIs of large players, e.g. Twitter, Github or Stripe, they all use simple ids.
HATEOAS. One common argument in favour of links is that it is aligned with HATEOAS. However, as far as I know, this relates to additional links in API responses rather than using links in payloads of POST requests.
All in all, I would go for simple ids, since I haven't yet heard a compelling argument favouring links, which would beat the aforementioned.
You are missing two important things here.
You need a standard way to describe forms in the response, in this case your POST form.
The information about the group ids / uris, or how to get them has to be described in the form in a standard way.
For example a HTML FORM with a SELECT INPUT would be RESTful. The closest thing we got in json to do the same is json-ld and hydra. But if you are obsessed with hal, then use hyperagent forms or something like that. It will never be a standard, but if compatibility is not an issue, then it is good enough.
To answer your question, you should use the id, because the server knows how to interpret it. The client needs the resource identifiers, the server needs it only in the uri part of the request, not in the body.
From my experience, it is always best to go with the simplest solution for making requests.
The process of generating a new url and parsing it seems excessive to get a resource, whereas sending the id of the item you want seems much simpler.
Thus, I would send a request in the form:
{
"name": "Batman",
"group": 1
}
I am creating a desktop application using node-webkit.
The purpose of creating the application is to add documents and that anyone can comment on the document. The document will be split into paragraphs and people can comment on the paragraphs. Each of the paragraphs will be considered as different sections. I would like to link each section (or paragraph) with the comments using JSON-LD.
I am new to JSON-LD and I would like to know how it can be used.
In a document (an HTML document, anyway), sections (or any element) can be identified using the #id attribute, which typically becomes a fragment identifier for the document. For instance, http://www.w3.org/TR/json-ld/#abstract is a URL with the "abstract" fragment identifier, if you look at the html source, you'll see the following:
<section id="abstract" class="introductory" property="dcterms:abstract" datatype="" typeof="bibo:Chapter" resource="#abstract" rel="bibo:chapter"><h2 aria-level="1" role="heading" id="h2_abstract">Abstract</h2>
<p>JSON is a useful data serialization and messaging format.
This specification defines JSON-LD, a JSON-based format to serialize
Linked Data. The syntax is designed to easily integrate into deployed
systems that already use JSON, and provides a smooth upgrade path from
JSON to JSON-LD.
It is primarily intended to be a way to use Linked Data in Web-based
programming environments, to build interoperable Web services, and to
store Linked Data in JSON-based storage engines.</p>
</section>
(note that some of this is automatically generated, so there is other non-relevant boiler plate as well).
This provides you one mechanism of describing the structure of a document using JSON-LD:
{
"#id": "http://www.w3.org/TR/json-ld",
"#type": "bibo:Document",
"bibo:chapter": [{
"#id": "#abstract"
}, {
"#id": "#sotd"
}, {
"#id": "#references"
}],
}
Note, in this case, the JSON-LD is defined to have the same URI (URL) of the HTML document, so the "#abstract" really expands to http://www.w3.org/TR/json-ld#abstract, this providing you a way to reference that section, and an identifier for the section. Much more is possible.
In fact, many W3C specifications are marked up in RDFa, as both RDFa and JSON-LD are RDF formats, you can actually turn this document into JSON-LD with an appropriate too, such as the RDF distiller I maintain. For example, try the following in your browser: http://rdf.greggkellogg.net/distiller?fmt=jsonld&in_fmt=rdfa&uri=http://www.w3.org/TR/json-ld/#abstract.
I'm trying to wrap my head around designing a simple Wiki style app. In a traditional wiki, say wikipedia, are 'links' referenced in any kind of backend/complex way? Ie HABTM... or are links simply links?
I'm trying to decide myself what to do, a bit different but similar. I have pages written by individuals which they can attribute to themselves or credit a.. say a famous author. Should I save this attribution as merely a tag? The tag would create a reference to the famous person, which may or may not exist, but could also be created, but nothing more than a link. OR, do I dive deep and create a real data relationship (HABTM) ?
Thoughts?
A SQL-style Has And Belongs To Many mapping table is never necessary in Mongo.
If you'd like to provide, for example, a "what links here" view for a page, then I would do something like this for each page in your Wiki. I'll give an example of a page about pandas:
{
_id: "Panda",
text: "Page's contents go here",
links: ["Raccoon", "Weasel"]
}
You're using the page's title as its _id. To find titles of pages that link to "Raccoon", you can query like:
db.pages.find({"links": "Raccoon"})
Obviously, you should make an index on "links".