Metagrid widget api reference -

The client plugins are not what you are looking for, or you have some advanced use cases? Here is the reference for the widget endpoint. With this, you can build your own implementation.

The widget endpoint checks if a given resource is in concordance and returns a filtered list of the linked resources. The filtering is configured on the server.

URL

/widget/{provider-slug}/{kind}/{identifier}.json?callback=jsonpFn&inculde=false&language=de
Method

GET
URL Params

Required:

provider-slug=[string] Your provider slug f.e. dodis

kind=[enum] The kind of resource you request. Currently, only “person” is supported

identifier=[string] The identifier of the person
Optional:

language=[enum] Define a language for the names and descriptions of the providers in the response. Possible values [de, fr, en, it]. Deafult=de

include=[boolean] Include additional descriptions of the provider in the response. Default=false

callback=[string] If you want to get a JSONP response, you have to define a callback. This is no longer recommended. Please use JSON with cores headers.
Success Response:
- Code: 200
  
  Content: [{"provider-name-1":"https://link-to-resource-2","provider-name-2":"https://link-to-resource-2"}]
  
  OR
  
  If you turn on include param you will get the following response
- Code: 200
  
  Content: [{"provider-name-1": { "url": "https://link-to-resource-2", "short_description": "Short description of the provider", "long_description": "Long description of the provider"}, "provider-name-2":{ "url": "https://link-to-resource-2", "short_description": "Short description of the provider 2", "long_description": "Long description of the provider 2"}}]
Error Response:
- Code: 404
  
  Content: {"error": "Not Found", "message": "Not Found", "statusCode":404}
  
  Description: No concordance was found for the queried resource.
- Code: 404
  
  Content: 404 page not found
  
  Description: Wrong url f.e. the provider with the provider-slug does not exist.
- Code: 400
  
  Content: {"error": "Bad Request", "message": "Error message", "statusCode": 400}
  
  Description: One of the params has the wrong type or format
- Code: 500
  
  Content: {"error": "Internal Error", "message": "Error message", "statusCode": 500}
  
  Description: Something went wrong. Please contact us.
Sample Call:

fetch('https://api.metagrid.ch/widget/dodis/person/5.json')
    .then(r => r.json())
    .then(r => console.log(r[0]));

Faire use

There are no limits to this service. If you hammer on it, it will slow down and at some point stop working. So please don’t open more than 10 parallel connections and be nice. If we detect too much abuse we will introduce rate limits.
The ugliness of the API and some warnings

The API format is old and exists since 2012. Today we would make things differently:
- The response is an array with length 1, containing one big object. WTF! Unfortunately yes. This was a bug back in 2014, but we settled on this schema and we have too many widgets out there to change it.
- Ok, wait “person” is the only possible key for the “kind” param, you are kidding? Yes, that’s true. Until 2015 there were other keys like “place” and “tag”, but we focused on persons. So “person” is the only valid key.
- You return a 404 if there is no concordance for a queried person. This pollutes the error console of the end user. Nooo! From the semantic point of view, 404 is correct. There is no result for the queried resource. But you are right, this can confuse end users.
- The identifier is the id of the person in my DB? Wat! You are right, Metagrid models concordance as a group of identifiers from different partners. Often the most stable thing is the id in the database of a partner. Ok, but the id is something a partner controls, what if they decide to change it? Then everything will break, no? Metagrid relies on stable identifiers, so please don’t change them! This is the contract between Metagrid and the partners (see also our code of conduct). Changing the identifier would not just destroy your Metagrid linking, but also all the printed references to your entry. If you have to change them, please inform us.

Docs

Metagrid widget api reference