Fork me on GitHub
Phraseanet Documentation

Table Of Contents

You are currently viewing the version 4.1. View another version : 

API Changelog

2.0.0

Version 2.0.0 of Phraseanet API is brought with Phraseanet.

New routes

1.5.0

Version 1.5.0 of Phraseanet API is brought with Phraseanet 3.8.8.

New route

  • embed/substitute

    Substitute / inject a sub-definition for a record of type document

Updated routes

  • record/add

    Add an attribute “nosubdefs” to prevent creation of sub-definitions

  • record/embed

    Add informations “substituted”, “created_on”, “updated_on” for embeds

1.4.1

Version 1.4.1 of Phraseanet API is brought with Phraseanet 3.8.6. This upgrade is fully backward compatible and features new accept headers:

  • “application/vnd.phraseanet.record-extended+json”
  • “application/vnd.phraseanet.record-extended+yaml”
  • “application/vnd.phraseanet.record-extended+jsonp”

Those extended headers allows to get more information (sub-definitions, caption...*etc*.).about a record in a single request.

1.4.0

Version 1.4.0 of Phraseanet API is brought with Phraseanet 3.8.4. This upgrade is fully backward compatible, adds a new route to get information about the current authenticated user.

New routes

  • me User route

Updated routes

  • feeds/aggregated adds feeds attribute to restrict aggregated feeds

    on given feed ids.

  • feeds/entry adds a feed_title attribute that refers to the title of the feed

    where the entry is located.

1.3.1

Version 1.3.1 of Phraseanet API is brought with Phraseanet 3.7.9. This upgrade is fully backward compatible, enhances permalinks URLs and adds a download URL.

Note

Backward compatibility is preserved for URLs that have been generated with previous API version.

Before

{
    "name": "preview",
    "permalink": {
        "created_on": "2012-12-19T18:46:17+01:00",
        "id": 249,
        "is_activated": true,
        "label": "SUPER",
        "updated_on": "2012-12-19T18:46:17+01:00",
        "page_url": "http://local.phrasea/permalink/v1/SUPER/1/99/9p6yOZMJ/preview/view/",
        "url": "http://local.phrasea/permalink/v1/SUPER/1/99/9p6yOZMJ/preview/"
    },
    "height": 533,
    "width": 800,
    "filesize": 26853,
    "devices": [],
    "player_type": "IMAGE",
    "mime_type": "image/jpeg"
}

version 1.3.1

{
    "name": "preview",
    "permalink": {
        "created_on": "2012-12-19T18:46:17+01:00",
        "id": 249,
        "is_activated": true,
        "label": "SUPER",
        "updated_on": "2012-12-19T18:46:17+01:00",
        "page_url": "http://local.phrasea/permalink/v1/1/99/preview/?token=9p6yOZMJ",
        "download_url": "http://local.phrasea/permalink/v1/1/99/preview/SUPER.jpg?token=9p6yOZMJ&download"
        "url": "http://local.phrasea/permalink/v1/1/99/preview/SUPER.jpg?token=9p6yOZMJ",
    },
    "height": 533,
    "width": 800,
    "filesize": 26853,
    "devices": [],
    "player_type": "IMAGE",
    "mime_type": "image/jpeg"
}

1.3

Version 1.3 of Phraseanet API is brought with Phraseanet 3.7.5. This upgrade is fully backward compatible and introduces the concept of Story to the API.

New routes

Deprecated routes

  • records/search. We strongly encourage developers to upgrade their code to support the new API.

Updated routes

1.2

Version 1.2 of Phraseanet API is not backward compatible with the previous one.

Before

"response": {
    "items": {
        "1": {
            "item_id": 1,
        },
        "3": {
            "item_id": 3
        }
    }
}

version 1.2

"response": {
    "items": [
        {
            "item_id": 1,
        },
        {
            "item_id": 3
        }
    ]
}

Entries response from aggregated feeds

Attribute feed_id has been added, it describes the feed identifier of the entry.

Record response

Attribute last_modification has been replaced by updated_on.

Embedable medias response

The embedable media is now an array of embedable objects.

The name attribute has been added.

Before

"response": {
        "embed": {
          "document": {
                "permalink": {
                    "created_on": "2012-06-22T21:20:55+02:00",
                    "id": 1972,
                    "is_activated": true,
                    "label": "0113JPG",
                    "updated_on": "2012-06-22T21:20:55+02:00",
                    "page_url": "http://dev.phrasea.net/permalink/v1/0113JPG/1/633/gAZMiywc/document/view/",
                    "url": "http://dev.phrasea.net/permalink/v1/0113JPG/1/633/gAZMiywc/document/"
                },
                "height": 4256,
                "width": 2832,
                "filesize": 1101093,
                "devices": [
                "all"
                ],
                "player_type": "IMAGE",
                "mime_type": "image/jpeg"
            }
    }

version 1.2

"response": {
        "embed": [
        {
            "name": "document",
            "permalink": {
                "created_on": "2012-06-22T21:20:55+02:00",
                "id": 1972,
                "is_activated": true,
                "label": "0113JPG",
                "updated_on": "2012-06-22T21:20:55+02:00",
                "page_url": "http://dev.phrasea.net/permalink/v1/0113JPG/1/633/gAZMiywc/document/view/",
                "url": "http://dev.phrasea.net/permalink/v1/0113JPG/1/633/gAZMiywc/document/"
            },
            "height": 4256,
            "width": 2832,
            "filesize": 1101093,
            "devices": [
            "all"
            ],
            "player_type": "IMAGE",
            "mime_type": "image/jpeg"
        }

Record metadatas response

The response of a record metadatas is now contained in a record_metadatas attribute.

"response": {
    "record_metadatas": [
    {
        "meta_id": 4437,
        "meta_structure_id": 1,
        "name": "Object",
        "value": "smoke"
    },
    {
        "meta_id": 4438,
        "meta_structure_id": 4,
        "name": "Keywords",
        "value": "fumée"
    }
    ]
}

Databox document structure response

The response of a databox document structure is now contained in a document_metadatas attribute.

"response": {
         "document_metadatas": [
         {
             "id": 1,
             "namespace": "IPTC",
             "source": "IPTC:ObjectName",
             "tagname": "ObjectName",
             "name": "Object",
             "separator": "",
             "thesaurus_branch": "",
             "type": "string",
             "indexable": true,
             "multivalue": false,
             "readonly": false,
             "required": false
         },
         {
             "id": 2,
             "namespace": "IPTC",
             "source": "IPTC:Category",
             "tagname": "Category",
             "name": "Category",
             "separator": "",
             "thesaurus_branch": "",
             "type": "string",
             "indexable": true,
             "multivalue": false,
             "readonly": false,
             "required": false
         }
     ]
 }

Task response

Three fields have been added to the response that describe a task.

  • auto_start
  • runner
  • crash_counter
"response": {
    "task": {
        "id": 2,
        "name": "Subviews creation",
        "state": "started",
        "pid": 15705,
        "title": "Subviews creation",
        "last_exec_time": "2012-06-13T14:38:38+02:00",
        "auto_start": true,
        "runner": "scheduler",
        "crash_counter": 0
    }
}

Caption record response

The response of a caption record is now contained in caption_metadas attribute

"response": {
    "caption_metadatas": [
        {
            "meta_structure_id": 29,
            "name": "Bits",
            "value": "8"
        },
        {
            "meta_structure_id": 30,
            "name": "Channels",
            "value": "3"
        }
    ]
}

Basket response

A validation_basket attribute has been added to the basket response, it indicates whether it is a validation basket or not.

"response": {
    "basket": {
        "basket_id": 144,
        "created_on": "2012-06-18T16:29:37+02:00",
        "description": "",
        "name": "hello",
        "pusher_usr_id": null,
        "ssel_id": 144,
        "updated_on": "2012-06-18T16:29:37+02:00",
        "unread": false,
        "validation_basket": false
    }
}

Basket content response

The basket_elements at the root of the response returns only an array of basket elements.

A basket attribute has been added to the root of the response and describes the requested basket.

"response": {
    "basket_elements": [
        {
            "basket_element_id": 9,
            "order": 4,
            "record": {

            }
        }
    ],
    "basket": {
        "basket_id": 144,
        "created_on": "2012-06-18T16:29:37+02:00",
        "description": "",
        "name": "hello",
        "pusher_usr_id": null,
        "ssel_id": 144,
        "updated_on": "2012-06-18T16:29:37+02:00",
        "unread": false,
        "validation_basket": false
    }
}

The choice attribute has been replace by validation_choices which now contains an array of validation choice with a new validation_user attribute.

version 1.2

{
    "basket_element_id": 25,
    "order": 7,
    "phrasea_type": "image",
    "uuid": "fc766012-a9c8-49eb-bcbd-c6f5270cb6f5"
    "validation_item": true,
    "record": {
        ...
    },
    "technical_informations": [
        ...
    ],
    "validation_choices": [
    {
        "validation_user": {
            "usr_id": 3,
            "usr_name": "durand.t@gmail.com",
            "confirmed": false,
            "can_agree": true,
            "can_see_others": true,
            "readonly": false
        },
        "agreement": null,
        "updated_on": "2012-06-29T16:32:50+02:00",
        "note": ""
    },
    {
        "validation_user": {
            "usr_id": 722,
            "usr_name": "martin.s@yahoo.com",
            "confirmed": false,
            "can_agree": true,
            "can_see_others": true,
            "readonly": true
        },
        "agreement": null,
        "updated_on": "2012-06-29T16:32:50+02:00",
        "note": ""
    }
    ],
    "agreement": null,
    "note": ""
}

Searching for a records

Some parameters from records/search have been renamed:

  • datefield => date_field
  • datemin => date_min
  • datemax => date_max

The page parameter from the request and the associated response field have been replaced by offset_start

"response": {
    "offset_start": 0,
    "per_page": 10,
    "available_results": 1,
    "total_results": 1,
    "error": "",
    "warning": "",
    "query_time": 0.000342,
    "search_indexes": "",
    "suggestions": [],
    "results": [{
        ....
     }]
}

Feeds response

Attribute is_mine has been removed and is replaced by two new attributes: readonly and deletable.

"feeds": {
    "288": {
        "id": 288,
        "title": "News",
        "subtitle": "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo. ",
        "total_entries": 0,
        "icon": "/skins/icons/rss32.gif",
        "public": false,
        "readonly": true,
        "deletable": false,
        "created_on": "2011-07-20T18:45:20+02:00",
        "updated_on": "2011-07-20T18:45:20+02:00"
    },

Note

These attributes have also been added in feeds/list.

Bug fix

feed content route response was looking like

"response": {
    "offset_start": 0,
    "entries": {
        "offset_start": 0,
        "entries": {
            ...
        }
    }
}

This wrong behavior has been fixed and the response is correctly returned as of 1.2.

"response": {
    "offset_start": 0,
    "entries": {
        ...
    }
}

Route add

Thumbnails

Before 1.2, a substitution file was provided by the API when a record thumbnail was not available. This substitution file is not provided anymore. Thus, the thumbnail key can be null:

{
    "meta": {
        "api_version": "1.3",
        "request": "GET /api/v1/records/2/132/",
        "response_time": "2012-06-13T14:06:21+02:00",
        "http_code": 200,
        "error_type": null,
        "error_message": null,
        "error_details": null,
        "charset": "UTF-8"
    },
    "response": {
        "record": {
            "databox_id": 2,
            "record_id": 132,
            "mime_type": "image/jpeg",
            "title": "photo03.JPG",
            "original_name": "photo03.JPG",
            "last_modification": "2012-06-13T13:50:29+02:00",
            "created_on": "2012-06-13T13:49:29+02:00",
            "collection_id": 1,
            "sha256": "60691f538bdac78197004edcfb77dc772d824daeca54bd13e59f6b485f0293bc",
            "thumbnail": null,
            "technical_informations": {
                "Height": 2448,
                "Width": 3264
            },
            "phrasea_type": "image",
            "uuid": "d91372ec-ea94-4e8a-bf26-065ad8684180"
        }
    }
}

Embeddables

Embeddable media now provides a list of supported devices. This devices are compatible with CSS2 specification.

See also

http://www.w3.org/TR/CSS2/media.html#media-types

The following thumbnail is compatible with a screen display

"thumbnail": {
    "width": 150,
    "filesize": 4271,
    "devices": [
        "screen"
    ],
    "mime_type": "image/jpeg"
},

Request a media depending on device and/or mime type

You can now restrict to some devices and/or mime types in the records/embed route.

1.1

A major schema enhancement happens for meta values. Multivalued stored serialized are now stored separatly. Two routes are modified: records/metadatas and records/setmetadatas. A route has been added to make it easy to display caption: records/caption.

This enhancement allows to store ressource in multivalued fields like users, geoname entities, Thesaurus entries...

The main consequence is a change in two API routes: records/metadatas and records/setmetadatas, therefore the upgrade of API to version 1.1.

Route records/metadatas

Route records/metadatas was returning results like:

"6272": {                    //Monovalued field
    "meta_id": 6272,
    "meta_structure_id": 2,
    "name": "Categorie",
    "value": "paysages"
},
"6273": {                    //Monovalued field
    "meta_id": 6273,
    "meta_structure_id": 4,
    "name": "MotsCles",
    "value": [
        "ciel",
        "météo",
        "nuage"
    ]
}

Responses in API 1.1 are now like:

"6272": {                    //Monovalued field value
    "meta_id": 6272,
    "meta_structure_id": 2,
    "name": "Categorie",
    "value": "paysages"
},
"6273": {                    //Multivalued field value
    "meta_id": 6273,
    "meta_structure_id": 4,
    "name": "MotsCles",
    "value": "ciel"
},
"6274": {                    //Multivalued field value
    "meta_id": 6274,
    "meta_structure_id": 4,
    "name": "MotsCles",
    "value": "météo"
},
"6275": {                    //Multivalued field value
    "meta_id": 6275,
    "meta_structure_id": 4,
    "name": "MotsCles",
    "value": "nuage"
}

Route records/caption

For developers who were using this route to display caption, we add the route records/caption which is easier in that case. You should use records/metadatas when you’re planning to edit metadatas.

"2": {                         //Monovalued field value
    "meta_structure_id": 2,
    "name": "Categorie",
    "value": "paysages"
},
"4": {                         //Multivalued field serialized
    "meta_structure_id": 4,
    "name": "MotsCles",
    "value": "ciel ; météo ; nuage"
}

See also

complete documentation for route records/caption

Route records/setmetadatas

La route records/setmetadatas was working like this:

// HTTP parameters:
metadatas = {
    //Add a value in a monovalued field
    {
        meta_struct_id: 1,
        meta_id: null,
        value: [
            'A pretty string'
        ]
    },
    //Update a value in a multivalued field
    {
        meta_struct_id: 3,
        meta_id: 487,
        value: [
            'one key word',
            'two key word'
        ]
    },
    //Delete a value
    {
        meta_struct_id: 7,
        meta_id: 489,
        value: []
    }
}

Now, you must use it like this:

metadatas = {
    //Add a value in a monovalued field
    {
        meta_struct_id: 1,
        meta_id: "",
        value: 'A pretty string'
    },
    //Update a value in a multivalued field
    {
        meta_struct_id: 3, //champ multivalué
        meta_id: 487,
        value: 'one key word'
    },
    //Add a value in a multivalued field
    {
        meta_struct_id: 3, //champ multivalué
        meta_id: "",
        value: 'second key word'
    },
    //Delete a value in a multivalued field
    {
        meta_struct_id: 3, //champ multivalué
        meta_id: 487,
        value: ""
    },
    //Add a value in a monovalued field
    {
        meta_struct_id: 7,
        meta_id: 489,
        value: ""
    }
}

1.0

First stable version of Phraseanet API. The API uses OAuth2 as authentication and provides GET/POST routes to access ressources.

English French Cookie policy Privacy policy
© Copyright 2004-2021, Alchemy. Created using Sphinx 1.3.6.