NAV
shell

Introduction

Welcome to the RMN-GP API documentation! You will soon be able to use our API to access RMN-GP API endpoints, and retrieve information in the JSON format on various artworks, artists, and related pictures in our database.

This documentation should help you discover our API, and includes some examples using curl, on the right-most pane. You can also explore the API live using our Javascript console.

Versioning

All API calls must specify which API version to use. This version identifier ensures that API will not introduce major changes for the given version.

You can get the last API version by requesting the root API endpoint: https://api.art.rmngp.fr/art

Then prefix all paths with this version number, for example: https://api.art.rmngp.fr/v1/api_endpoint_here.

curl -H "ApiKey: demo" \
     "https://api.art.rmngp.fr/"

The above command returns JSON structured like this:




Authentication





To be authorized, you will need to include the key in HTTP request headers:




curl -H "ApiKey: demo" \
     "https://api_endpoint_here"






Make sure to replace demo with your API key.





RMN-GP uses API keys to allow access to the API. You will soon be able to request one on our partners’ site.



RMN-GP expects the API key to be included in all API requests to the server in a
HTTP header that looks like the following:



ApiKey: demo





Errors





The RMN-GP API uses the following error codes:






Error Code
Meaning





400
Bad Request – Your request sucks




401
Unauthorized – Your API key is wrong




403
Forbidden – The requested resource is not accessible




404
Not Found – The specified resource could not be found




405
Method Not Allowed – You tried to access a resource with an invalid method




406
Not Acceptable – You requested a format that isn’t json




410
Gone – The requested resource has been removed from our servers




418
I’m a teapot




429
Too Many Requests – You’re requesting too many resources! Slow down!




500
Internal Server Error – We had a problem with our server. Try again later.




503
Service Unavailable – We’re temporarily off-line for maintenance. Please try again later.






Images



Some endpoints return images, here the stucture:







Example




{
  "id": 167,
  "identifier": "06-528589",
  "urls": {
    "original": "https://api.art.rmngp.fr/v1/images/1/167?t=thisisaprivatetoken",
    "small": {
      "width": 95,
      "height": 95,
      "type": "resize",
      "url": "https://api.art.rmngp.fr/v1/images/1/167/s?t=thisisaprivatetoken"
    },
    "thumbnail": {
      "width": 190,
      "height": 190,
      "type": "resize",
      "url": "https://api.art.rmngp.fr/v1/images/1/167/t?t=thisisaprivatetoken"
    },
    "medium": {
      "width": 379,
      "height": 379,
      "type": "resize",
      "url": "https://api.art.rmngp.fr/v1/images/1/167/m?t=thisisaprivatetoken"
    },
    "large": {
      "width": 758,
      "height": 758,
      "type": "resize",
      "url": "https://api.art.rmngp.fr/v1/images/1/167/l?t=thisisaprivatetoken"
    }
  }
}




Search



Response



The response consists of 2 sections:



Hits



This section contains the results of your search. Check the Elastic Search
documentation
for more informations.



In short, this section is structured like this:





Facets



This section contains the facets related to your search.
Each aggregation is defined by a key, and contains many buckets. Buckets are
the available facets for the current search.



Facet structure looks like this:





Pagination



When listing or searching documents, the API always returns paginated results.
The default is to return 10 results per page.



The total number of results matching a Query is indicated by the total key,
immediately under the hits key.



To get another results page, just add these parameters:









To change page, simply pass a page parameter to your request URL.




curl -H "ApiKey: demo" \
     "https://api.art.rmngp.fr/v1/works?page=2"






Sample results, matching a total of 42 documents.




{
  "hits": {
    "total": 42,
    "hits": []
  }
}




Full text



When you want to search for documents, you can perform a full text using the q
parameter.



This parameter uses the
Query String Query
format of Elastic search API.



Here are some examples.



If you want to search on all fields, just provide a string: la joconde.


curl -H "ApiKey: demo" \
     'https://api.art.rmngp.fr/v1/works.json?q=la%20joconde'

curl -H "ApiKey: demo" \
     'https://api.art.rmngp.fr/v1/works.json?q=la%20joconde&lang=fr'




By default, the search is made on all tha available languages. You can limit
the search to a specific language by using the lang parameter. It can
improve the relevancy of results by using a more precise analyzer.



Matching a field



Alternatively, you can select a field to search for, if you want to match an
exact value on only the title, use title:"la joconde". You can use this to
limit the results to a work with a specific id, like this: id:36238.


curl -H "ApiKey: demo" \
     'https://api.art.rmngp.fr/v1/works.json?q=title:"la%20joconde"'

curl -H "ApiKey: demo" \
     'https://api.art.rmngp.fr/v1/works.json?q=id:36238'






The full text search is good but sometime you want something more precise when
you do a search in an API : it’s possible.



For exemple, you want to search la joconde but you only want to have result
that are drawed : you can pass "joconde AND techniques.name=dessin" in the q
parameter.



You can do that with every terms of the works like periods, keywords, authors,…



You can also use the operand OR For exemple you can use
"joconde OR collection=estampes"


curl -H "ApiKey: demo" \
     "https://api.art.rmngp.fr/v1/works.json?q=la%20joconde%20AND%20techniques%3Ddessin"




Filtering facets



On works, authors and selections endpoints, facets are availables.



To filter on a facet, just add a facets[facet_name]=facet_value params to the
query string.



By default, only 10 items per facet are returned by the api. If you want more,
use the facet pagination.







For example, we have the following facets returned by the works endpoint:




  {
    "sources": {
      "buckets": [
        {
          "key": "INHA",
          "doc_count": 5977,
          "link": "https://api.art.rmngp.fr/v1/works?api_key=demo&facets%5Bsources%5D=INHA"
        },
        {
          "key": "BPK",
          "doc_count": 2,
          "link": "https://api.art.rmngp.fr/v1/works?api_key=demo&facets%5Bsources%5D=BPK"
        },
        {
          "key": "NATIONAL GALLERY OF LONDON",
          "doc_count": 1,
          "link": "https://api.art.rmngp.fr/v1/works?api_key=demo&facets%5Bsources%5D=NATIONAL+GALLERY+OF+LONDON"
        },
        {
          "key": "RMN",
          "doc_count": 1,
          "link": "https://api.art.rmngp.fr/v1/works?api_key=demo&facets%5Bsources%5D=RMN"
        },
        {
          "key": "RMN (musée du Louvre)",
          "doc_count": 1,
          "link": "https://api.art.rmngp.fr/v1/works?api_key=demo&facets%5Bsources%5D=RMN+%28mus%C3%A9e+du+Louvre%29"
        }
      ]
    }
  }






To filter works on the “RMN” source, add this params to the query string:
facets[sources]=RMN




          
Works



Definition



Attributes





Associations





Get All Works


curl -H "ApiKey: demo" \
     "https://api.art.rmngp.fr/v1/works"






The above command returns JSON structured like this:








This endpoint retrieves all artworks.



HTTP Request



GET https://api.art.rmngp.fr/v1/works



Query Parameters






Parameter
Default
Description





q

Filter results matching this query




lang

Limit the research to fields in this language (better relevance)




exists

Limit the research to works with these fields




exclude[keywords.name.fr][]

Array of keywords to exclude




exclude[techniques.name.fr][]

Array of techniques to exclude




exclude[authors.name.fr][]

Array of authors to exclude




exclude[periods.name.fr][]

Array of periods to exclude




exclude[collections.name.fr][]

Array of collections to exclude




exclude[geographies.name.fr][]

Array of geographies to exclude




exclude[location.name.fr][]

Array of locations to exclude




exclude[images.photographer.name][]

Array of photographer to exclude




exclude[schools.name.fr][]

Array of schools to exclude




exclude[images.source.name][]

Array of source to exclude




exclude[styles.name.fr][]

Array of styles to exclude




sort

Field used to sort results




order
asc
Sorting order, desc or asc.




page
1
Results page offset




per_page
10
Number of results per page




facet_page
1
Facet page offset




facet_per
10
Number of facets per page




facets[collections]

Filter on a collection facet




facets[locations]

Filter on a location facet




facets[authors]

Filter on a author facet




facets[periods]

Filter on a period facet




facets[techniques]

Filter on a technique facet




facets[styles]

Filter on a style facet




facets[schools]

Filter on a schools facet




facets[geographies]

Filter on a geography facet




facets[colors]

Filter on a color facet




filters[images.identifier]

Filter on an image identifier






For more specific search see Search





Get a specific work by its ID or slug


curl -H "ApiKey: demo" \
     "https://api.art.rmngp.fr/v1/works/:id"






The above command returns JSON structured like this:








This endpoint retrieves a specific work by its slug.



HTTP Request



GET https://api.art.rmngp.fr/v1/works/:id



Query Parameters






Parameter
Default
Description





id

A work ID or slug




count_me[user_id]

ID of user visiting the page




count_me[session_id]

Session ID of user visiting the page






Get suggested works


curl -H "ApiKey: demo" \
     "https://api.art.rmngp.fr/v1/works/suggested"






The above command returns JSON structured like this:








This endpoint retrieves a list of suggested works. You can provide a work_id to
get contextual suggestions.



HTTP Request



`GET https://api.art.rmngp.fr/v1/works/suggested



Query Parameters






Parameter
Default
Description





id

A work id




slug

A work slug




exists

Limit the research to works with these fields




exclude[keywords.name.fr][]

Array of keywords to exclude




exclude[techniques.name.fr][]

Array of techniques to exclude




exclude[authors.name.fr][]

Array of authors to exclude




exclude[periods.name.fr][]

Array of periods to exclude




exclude[collections.name.fr][]

Array of collections to exclude




exclude[geographies.name.fr][]

Array of geographies to exclude




exclude[location.name.fr][]

Array of locations to exclude




exclude[images.photographer.name][]

Array of photographer to exclude




exclude[schools.name.fr][]

Array of schools to exclude




exclude[images.source.name][]

Array of source to exclude




exclude[styles.name.fr][]

Array of styles to exclude




page
1
Results page offset




per_page
10
Number of results per page






Aggregations



The works endpoint can also decorate the response with some aggregation
computations. It works with the aggregation framework from
Elasticsearch.





For example, you can have some stats on the dimensions of the works painted
by Picasso. (see: aggregations.works_width and aggregations.works_height)




curl -H "ApiKey: demo" \
     "https://api.art.rmngp.fr/v1/works?q=Picasso&aggregates[][name]=works_width&aggregates[][type]=stats&aggregates[][field]=width&aggregates[][name]=works_height&aggregates[][type]=stats&aggregates[][field]=height"









The citizenship of the authors for the 19th century. (see: aggregations.authors_citizenship)




curl -H "ApiKey: demo" \
     "https://api.art.rmngp.fr/v1/works?aggregates[][name]=authors_citizenship&aggregates[][type]=terms&aggregates[][field]=authors.citizenship&facets[periods]=19e+siècle"







Most fields are tokenized and stemmed for a better full-text search. It can
give weird results for aggregation. In that case, you can try to append .raw
to the field name.



Parameters



To add an aggregation, you have to give 3 parameters:








Type
Description





min
Returns the minimum value among the numeric values extracted from the aggregated documents




max
Returns the maximum value among numeric values




sum
Sums up numeric values




avg
Computes the average of numeric values




stats
Computes stats over numeric values (min, max, sum, avg and count)




extended_stats
An extended version of the stats aggregation, where additional metrics are added such as sum_of_squares, variance and std_deviation




cardinality
Calculates an approximate count of distinct values




value_count
Counts the number of values that are extracted from the aggregated documents




missing
Counts all documents in the current document set context that are missing a field value




percentiles
Calculates percentiles over numeric values (1%, 5%, 25%, 50%, 75%, 95%, 99%)




terms
A multi-bucket value source based aggregation where buckets are dynamically built - one per unique value




significant_terms
Returns interesting or unusual occurrences of terms in a set (experimental!)




histogram
Dynamically builds fixed size (a.k.a. interval) buckets over the values




date_histogram
Same as histogram, but can use interval with not a fixed size (a month or a year for example)






For histograms, a fourth parameter, interval, will be given.


curl -H "ApiKey: demo" \
     "https://api.art.rmngp.fr/v1/works?aggregates[][name]=histogram&aggregates[][type]=date_histogram&aggregates[][field]=date.estimated_day&aggregates[][interval]=month"






The above command returns JSON structured like this:







          
Authors



List all authors present on the API.



Definition



Attributes





Associations





Get All Authors


curl -H "ApiKey: demo" \
     "https://api.art.rmngp.fr/v1/authors"






The above command returns JSON structured like this:








This endpoint retrieves all know authors.



HTTP Request



GET https://api.art.rmngp.fr/v1/authors



Query Parameters






Parameter
Default
Description





q

Filter results matching this query




sort

Field used to sort results




order
asc
Sorting order, desc or asc.




page
1
Results page offset




per_page
10
Number of results per page




facet_page
1
Facet page offset




facet_per
10
Number of facets per page




facets[collections]

Filter on a collection facet




facets[locations]

Filter on a location facet




facets[periods]

Filter on a period facet




facets[techniques]

Filter on a technique facet




facets[geographies]

Filter on a geography facet






For more specific search see Search




          
Thesaurus



Get all resources


curl -H "ApiKey: demo" \
     "https://api.art.rmngp.fr/v1/thesaurus/collections"






The above command returns JSON structured like this:








Thesaurus consists of several types of resources that are searchable in the same way.



HTTP Request



GET https://api.art.rmngp.fr/v1/thesaurus/$resource_type



Where $resource_type is one of:





Query Parameters






Parameter
Default
Description





q

Filter results matching this query




page
1
Results page offset




per_page
10
Number of results per page






For more specific search see Search




          
Collections


curl -H "ApiKey: demo" \
     "https://api.art.rmngp.fr/v1/thesaurus/collections"






The above command returns JSON structured like this:








Collections are arbitrary groups of works.



Definition



Attributes





Get All Collections



This endpoint retrieves all known collections.



HTTP Request



GET https://api.art.rmngp.fr/v1/thesaurus/collections



Query Parameters






Parameter
Default
Description





q

Filter results matching this query




filters[level]

Filter on a specific level of the thesaurus hierarchy




page
1
Results page offset




per_page
10
Number of results per page






For more specific search see Search


          
Geographies


curl -H "ApiKey: demo" \
     "https://api.art.rmngp.fr/v1/thesaurus/geographies"






The above command returns JSON structured like this:








Geographies are places in the world where the works was done or founded.



Definition



Attributes





Get All Geographies



This endpoint retrieves all know geographies.



HTTP Request



GET https://api.art.rmngp.fr/v1/thesaurus/periods



Query Parameters






Parameter
Default
Description





q

Filter results matching this query




filters[level]

Filter on a specific level of the thesaurus hierarchy




page
1
Results page offset




per_page
10
Number of results per page






For more specific search see Search


          
Keywords


curl -H "ApiKey: demo" \
     "https://api.art.rmngp.fr/v1/thesaurus/keywords"






The above command returns JSON structured like this:








Keywords contain all the keyword that has no special type.



Definition



Attributes





Get All keywords



This endpoint retrieves all keywords.



HTTP Request



GET https://api.art.rmngp.fr/v1/thesaurus/keywords



Query Parameters






Parameter
Default
Description





q

Filter results matching this query




filters[level]

Filter on a specific level of the thesaurus hierarchy




page
1
Results page offset




per_page
10
Number of results per page






For more specific search see Search


          
Locations


curl -H "ApiKey: demo" \
     "https://api.art.rmngp.fr/v1/thesaurus/locations"






The above command returns JSON structured like this:








Locations are the differents museeum where the works are.



Definition



Attributes





Get All Locations



This endpoint retrieves all know locations.



HTTP Request



GET https://api.art.rmngp.fr/v1/thesaurus/locations



Query Parameters






Parameter
Default
Description





q

Filter results matching this query




page
1
Results page offset




per_page
10
Number of results per page






For more specific search see Search


          
Periods


curl -H "ApiKey: demo" \
     "https://api.art.rmngp.fr/v1/thesaurus/periods"






The above command returns JSON structured like this:








Periods can be a century, an age, or a period.



Definition



Attributes





Get All Periods



This endpoint retrieves all know periods.



HTTP Request



GET https://api.art.rmngp.fr/v1/thesaurus/periods



Query Parameters






Parameter
Default
Description





q

Filter results matching this query




filters[level]

Filter on a specific level of the thesaurus hierarchy




page
1
Results page offset




per_page
10
Number of results per page






For more specific search see Search


          
Photographers


curl -H "ApiKey: demo" \
     "https://api.art.rmngp.fr/v1/thesaurus/photographers"






The above command returns JSON structured like this:








Authors of the many images available through the API.



Definition



Attributes





Get All Photographers



This endpoint retrieves all know photographers.



HTTP Request



GET https://api.art.rmngp.fr/v1/thesaurus/photographers



Query Parameters






Parameter
Default
Description





q

Filter results matching this query




page
1
Results page offset




per_page
10
Number of results per page






For more specific search see Search


          
Schools


curl -H "ApiKey: demo" \
     "https://api.art.rmngp.fr/v1/thesaurus/schools"






The above command returns JSON structured like this:








Schools are artistic schools.



Definition



Attributes





Get All Schools



This endpoint retrieves all know schools.



HTTP Request



GET https://api.art.rmngp.fr/v1/thesaurus/schools



Query Parameters






Parameter
Default
Description





q

Filter results matching this query




filters[level]

Filter on a specific level of the thesaurus hierarchy




page
1
Results page offset




per_page
10
Number of results per page






For more specific search see Search


          
Sources


curl -H "ApiKey: demo" \
     "https://api.art.rmngp.fr/v1/thesaurus/sources"






The above command returns JSON structured like this:








Sources are the museum where the works come from : you can also find the copyright in that part.



Definition



Attributes





Get All Sources



This endpoint retrieves all know sources.



HTTP Request



GET https://api.art.rmngp.fr/v1/thesaurus/sources



Query Parameters






Parameter
Default
Description





q

Filter results matching this query




page
1
Results page offset




per_page
10
Number of results per page






For more specific search see Search


          
Styles


curl -H "ApiKey: demo" \
     "https://api.art.rmngp.fr/v1/thesaurus/styles"






The above command returns JSON structured like this:








Styles of the many works available through the API.



Definition



Attributes





Get All Styles



This endpoint retrieves all know collections.



HTTP Request



GET https://api.art.rmngp.fr/v1/thesaurus/collections



Query Parameters






Parameter
Default
Description





q

Filter results matching this query




filters[level]

Filter on a specific level of the thesaurus hierarchy




page
1
Results page offset




per_page
10
Number of results per page






For more specific search see Search


          
Techniques


curl -H "ApiKey: demo" \
     "https://api.art.rmngp.fr/v1/thesaurus/techniques"






The above command returns JSON structured like this:








Techniques used by many works available through the API.



Definition



Attributes





Get All Techniques



This endpoint retrieves all know techniques.



HTTP Request



GET https://api.art.rmngp.fr/v1/thesaurus/techniques



Query Parameters






Parameter
Default
Description





q

Filter results matching this query




filters[level]

Filter on a specific level of the thesaurus hierarchy




page
1
Results page offset




per_page
10
Number of results per page






For more specific search see Search


          
Users



The users API allows partners to create, and destroy user accounts.



Create a user account



Partners with an API access are allowed to create user accounts.



HTTP Request



POST https://api.art.rmngp.fr/v1/users



Parameters






Parameter
Default
Description





name

user’s name (mandatory).




email

user’s email which must be unique in the whole API (mandatory).




password

user’s password: it must be at least 8 characters (mandatory).




firstname

user’s firstname.




lastname

user’s lastname.




newsletter_optin
false
Newsletter opt in.




language
fr
user’s firstname.




avatar

user avatar file






HTTP Response



Upon successful creation, the server replies with a 201 HTTP status code, and
returns the newly created user in JSON format. Any other status code indicate a
failure to create the user.




curl -H'ApiKey: demo' \
     'https://api.art.rmngp.fr/v1/users' -XPOST \
     -d'name=User%20name&email=user@example.com&password=password'






On success, the above command results in a 201 HTTP code, and returns JSON
structured like this:




{
    "id":               1,
    "email":            "user@example.com",
    "name":             "User",
    "firstname":        "Foo",
    "lastname":         "Bar",
    "partner_id":       1,
    "newsletter_optin": true,
    "language":         "fr",
    "created_at":       "2014-09-01T00:00:00.42Z",
    "updated_at":       "2014-09-01T00:00:00.42Z",
    "avatar": {
      "thumb": "http://example.com/avatar_thumb.jpg",
      "medium": "http://example.com/avatar_medium.jpg",
      "big": "http://example.com/avatar_big.jpg"
    }
}






If your request contains errors, you will receive a 400 HTTP status code,
and a JSON array listing the detected errors. For example:




[
  ["email",    "is missing"],
  ["password", "is missing"]
]




Update a user account



Partners with an API access are allowed to update user accounts.



HTTP Request



PUT https://api.art.rmngp.fr/v1/users/:id



Parameters






Parameter
Default
Description





name

user’s name.




email

user’s email which must be unique in the whole API.




password

user’s password: it must be at least 8 characters.




firstname

user’s firstname.




lastname

user’s lastname.




newsletter_optin
false
Newsletter opt in.




language
fr
user’s firstname.




avatar

user avatar file






HTTP Response



Upon successful update, the server replies with a 20O HTTP status code, and
returns the newly updated user in JSON format. Any other status code indicate a
failure to update the user.


curl -H'ApiKey: demo' \
     'https://api.art.rmngp.fr/v1/users/1' -XPUT \
     -d'name=User%20name&email=user@example.com&password=password'






On success, the above command results in a 200 HTTP code, and returns JSON
structured like this:




{
    "id":               1,
    "email":            "user@example.com",
    "name":             "User",
    "firstname":        "Foo",
    "lastname":         "Bar",
    "partner_id":       1,
    "newsletter_optin": true,
    "language":         "fr",
    "created_at":       "2014-09-01T00:00:00.42Z",
    "updated_at":       "2014-09-01T00:00:00.42Z",
    "avatar": {
      "thumb": "http://example.com/avatar_thumb.jpg",
      "medium": "http://example.com/avatar_medium.jpg",
      "big": "http://example.com/avatar_big.jpg"
    }
}




Destroy a user account



User accounts created by a partner can be destroyed by the same partner,
identified by their API key.



HTTP Request



DELETE https://api.art.rmngp.fr/v1/users/:id



HTTP Response



The server should reply with a 200 HTTP status code when the user is
successfully destroyed.




curl -H'ApiKey: demo' \
     'https://api.art.rmngp.fr/v1/users/1' -XDELETE






On success, the above command results in a 200 HTTP code, and returns the 
JSON representation of the destroyed user. For example:




{
    "id":         1,
    "name":       "User name",
    "partner_id": 1,
    "email":      "user@example.com",
    "created_at": "2014-09-01T00:00:00.42Z",
    "updated_at": "2014-09-01T00:00:00.42Z",
    "avatar": {
      "thumb": "http://example.com/avatar_thumb.jpg",
      "medium": "http://example.com/avatar_medium.jpg",
      "big": "http://example.com/avatar_big.jpg"
    }
}




Authenticate a user account



Partners with an API access are allowed to authenticate user accounts.



HTTP Request



POST https://api.art.rmngp.fr/v1/users/authenticate



Parameters






Parameter
Default
Description





email
“”
user’s email (mandatory).




password
“”
user’s password (mandatory).






HTTP Response



Upon successful authentication, the server replies with a 200 HTTP status code,
and returns the corresponding user in JSON format. Any other status code indicate a
failure to authenticate the user.


curl -H'ApiKey: demo' \
     'https://api.art.rmngp.fr/v1/users/authenticate' -XPOST \
     -d'email=user@example.com&password=password'






On success, the above command results in a 200 HTTP code, and returns JSON
structured like this:




{
    "id":         1,
    "name":       "User name",
    "partner_id": 1,
    "email":      "user@example.com",
    "created_at": "2014-09-01T00:00:00.42Z",
    "updated_at": "2014-09-01T00:00:00.42Z",
    "avatar": {
      "thumb": "http://example.com/avatar_thumb.jpg",
      "medium": "http://example.com/avatar_medium.jpg",
      "big": "http://example.com/avatar_big.jpg"
    }
}



          
Selections



A selection, or selection folder, allows a user to select and
organize artworks found on the API.



There is no limit to the number of selections created for a particular user,
and there is no limit to the number of artworks that a selection may contain.





List selections



HTTP Request



GET https://api.art.rmngp.fr/v1/selections



Query Parameters






Parameter
Default
Description





user_id

Which user’s selections should we show?




page
1
Results page offset




per_page
10
Number of results per page




tags

comma separated list of tags




works[include]

Include works in results?




works[q]

Search for works




works[lang]
fr
Return works facets for this language (fr, en, de)




works[sort]

Sort works




works[per_page]
1
Number of works per page




works[page]
10
Works page offset




works[facet_per]
1
Number of works facets per page




works[facet_page]
10
Works facets page offset




works[facets][collections]

Filter works on a collection facet




works[facets][locations]

Filter works on a location facet




works[facets][authors]

Filter works on a author facet




works[facets][periods]

Filter works on a period facet




works[facets][techniques]

Filter works on a technique facet




works[facets][styles]

Filter works on a style facet




works[facets][schools]

Filter works on a school facet




works[facets][geographies]

Filter works on a geography facet




images[include]

Include images in results?




images[q]

Search for images




images[lang]
fr
Return images facets for this language (fr, en, de)




images[sort]

Sort images




images[per_page]
1
Number of images per page




images[page]
10
Works page offset




images[facet_per]
1
Number of images facets per page




images[facet_page]
10
Works facets page offset




images[facets][collections]

Filter images on a collection facet




images[facets][locations]

Filter images on a location facet




images[facets][authors]

Filter images on a author facet




images[facets][periods]

Filter images on a period facet




images[facets][techniques]

Filter images on a technique facet




images[facets][styles]

Filter images on a style facet




images[facets][schools]

Filter images on a school facet




images[facets][geographies]

Filter images on a geography facet






HTTP Response



On success, the server replies with a 200 HTTP status code, and returns a
list of selections in JSON.


curl -H'ApiKey: demo' 'https://api.art.rmngp.fr/v1/selections'






On success, the above command should yield a JSON array, structured as
follows:










If you pass the include[works]=true (and/or include[images]=true)
parameter, you should get a JSON array with the following structure
(the works and images keys are added):








Create a selection



HTTP Request



POST https://api.art.rmngp.fr/v1/selections



Parameters






Parameter
Default
Description





name

Selection’s name (mandatory)




description

Selection’s description




user_id

Selection’s owner (mandatory)




work_ids

Array of work IDs to associate




image_ids

Array of image IDs to associate






HTTP Response



Upon successful creation, the server replies with a 201 HTTP status code, and
returns the newly created selection in JSON format. Any other status code
indicate a failure to create the selection.


curl -H'ApiKey: demo' \
  'https://api.art.rmngp.fr/v1/selections' -XPOST -d'name=example&user_id=1'






On success, the above command should yield a JSON object, structured as
follows:




{
    "id":           1,
    "name":         "example",
    "description":  "Example",
    "user_id":      1,
    "default":      true,
    "updated_at":   "2014-09-01T00:00:00.42Z",
    "created_at":   "2014-09-01T00:00:00.42Z",
    "tags":         "Foo,Bar"
}




Update a selection



HTTP Request



PUT https://api.art.rmngp.fr/v1/selections/:id



Parameters






Parameter
Default
Description





id

Selection ID (mandatory)




name

Selection’s name




description

Selection’s description




user_id

Selection’s owner (mandatory)




work_ids

Array of work IDs to associate




image_ids

Array of image IDs to associate






HTTP Response



Upon successful update, the server replies with a 200 HTTP status code, and
returns the updated selection in JSON format. Any other status code indicate a
failure to update the selection.


curl -H'ApiKey: demo' \
  'https://api.art.rmngp.fr/v1/selections/:id' -XPUT -d'name=example&user_id=1'






On success, the above command should yield a JSON object, structured as
follows:




{
    "id":           1,
    "name":         "example",
    "description":  "Example",
    "user_id":      1,
    "default":      true,
    "updated_at":   "2014-09-01T00:00:00.42Z",
    "created_at":   "2014-09-01T00:00:00.42Z",
    "tags":         "Foo,Bar"
}




Destroy a selection



HTTP Request



DELETE https://api.art.rmngp.fr/v1/selections/:id



HTTP Response



The server should reply with a 200 HTTP status code, when the selection is
successfully destroyed.


curl -H'ApiKey: demo' \
     'https://api.art.rmngp.fr/v1/selections/1' -XDELETE






On success, the above command results in a 200 HTTP code, and returns the 
JSON representation of the destroyed selection folder. For example:




{
    "id":           1,
    "name":         "example",
    "description":  "Example",
    "user_id":      1,
    "default":      true,
    "updated_at":   "2014-09-01T00:00:00.42Z",
    "created_at":   "2014-09-01T00:00:00.42Z",
    "tags":         "Foo,Bar"
}




Get a selection





The above command returns JSON structured like this:








HTTP Request



GET https://api.art.rmngp.fr/v1/selections/:id



Query Parameters






Parameter
Default
Description





id

Selection ID (mandatory)




works[include]

Include works in results?




works[q]

Search for works




works[lang]
fr
Return works facets for this language (fr, en, de)




works[sort]

Sort works




works[per_page]
1
Number of works per page




works[page]
10
Works page offset




works[facet_per]
1
Number of works facets per page




works[facet_page]
10
Works facets page offset




works[facets][collections]

Filter works on a collection facet




works[facets][locations]

Filter works on a location facet




works[facets][authors]

Filter works on a author facet




works[facets][periods]

Filter works on a period facet




works[facets][techniques]

Filter works on a technique facet




works[facets][styles]

Filter works on a style facet




works[facets][schools]

Filter works on a school facet




works[facets][geographies]

Filter works on a geography facet




images[include]

Include images in results?




images[q]

Search for images




images[lang]
fr
Return images facets for this language (fr, en, de)




images[sort]

Sort images




images[per_page]
1
Number of images per page




images[page]
10
Works page offset




images[facet_per]
1
Number of images facets per page




images[facet_page]
10
Works facets page offset




images[facets][collections]

Filter images on a collection facet




images[facets][locations]

Filter images on a location facet




images[facets][authors]

Filter images on a author facet




images[facets][periods]

Filter images on a period facet




images[facets][techniques]

Filter images on a technique facet




images[facets][styles]

Filter images on a style facet




images[facets][schools]

Filter images on a school facet




images[facets][geographies]

Filter images on a geography facet






HTTP Response



The server should reply with a 200 HTTP status code.


curl -H'ApiKey: demo' \
     'https://api.art.rmngp.fr/v1/selections/1' -XGET






On success, the above command results in a 200 HTTP code, and returns the 
JSON representation of this selection folder. For example:








Add a work or an image to a selection



HTTP Request



POST https://api.art.rmngp.fr/v1/selections/:id/:document_type



Parameters






Parameter
Default
Description





id

Selection ID (mandatory).




document_type

Type of document to add, images or works (mandatory).




document_id

Document’s ID on the API (mandatory).




position

unsigned integer to choose the entry’s position (mandatory).






HTTP Response



Upon successful creation, the server replies with a 201 HTTP status code, and
returns a JSON object with the selected work ID, and its version number.



Any other status code indicate a failure to create the selection.


curl -H'ApiKey: demo' \
  'https://api.art.rmngp.fr/v1/selections/1/works' \
  -XPOST -d'work_id=42&position=1'






On success, the above command results in a 201 HTTP status code, and
should yield a JSON object, structured as follows:




{
    "id":             1,
    "selection_id":   1,
    "document_id":    42,
    "document_type":  "Work",
    "version_id":     1,
    "position":       1
}




Add an work or and image to the user default selection



HTTP Request



POST https://api.art.rmngp.fr/v1/selections/:user_id/default/:document_type



Parameters






Parameter
Default
Description





user_id

User ID (mandatory).




document_type

Type of document to add, images or works (mandatory).




document_id

Document’s ID on the API (mandatory).




position

unsigned integer to choose the entry’s position (mandatory).






HTTP Response



Upon successful creation, the server replies with a 201 HTTP status code, and
returns a JSON object with the selected work ID, and its version number.



Any other status code indicate a failure to create the selection.


curl -H'ApiKey: demo' \
  'https://api.art.rmngp.fr/v1/selections/42/default/works' \
  -XPOST -d'work_id=42&position=1'






On success, the above command results in a 201 HTTP status code, and
should yield a JSON object, structured as follows:




{
    "id":             1,
    "selection_id":   1,
    "document_id":    42,
    "document_type":  "Work",
    "version_id":     1,
    "position":       1
}




Remove a work or an image from a selection



HTTP Request



DELETE https://api.art.rmngp.fr/v1/selections/:selection_id/:document_type/:id



Parameters






Parameter
Default
Description





document_type

Type of document to add, images or works (mandatory).




document_id

Document’s ID on the API (mandatory).






HTTP Response



The server should reply with a 200 HTTP status code, when the work is
successfully removed from the selection.



If you try to delete from a selection folder that does not exist, or a work
that is not part of the selection, then the server replies with a 404 HTTP
error code.


curl -H'ApiKey: demo' \
     'https://api.art.rmngp.fr/v1/selections/1/works/42' -XDELETE






On success, the above command results in a 200 HTTP code, and returns the 
JSON representation of the destroyed entry. For example:




{
    "id":             1,
    "selection_id":   1,
    "document_id":    42,
    "document_type":  "Work",
    "version_id":     1,
    "position":       1
}



          
Autocomplete



Get suggestions for a string pattern, usefull for auto-completions.


curl -H "ApiKey: demo" \
     "https://api.art.rmngp.fr/v1/autocomplete?q=jacob"






The above command returns JSON structured like this:








HTTP Request



GET https://api.art.rmngp.fr/v1/autocomplete



Query Parameters






Parameter
Default
Description





q

Pattern to search




lang
fr
Specific language. fr and en are available




types
work,author,location,period,technique
Specific types of items to search. work, author, period, technique, location avalaible




per
5
Number of results to return.







      

      

          

                shell