├── .gitignore └── apiary.apib /.gitignore: -------------------------------------------------------------------------------- 1 | *~ 2 | *# 3 | *.swp 4 | 5 | -------------------------------------------------------------------------------- /apiary.apib: -------------------------------------------------------------------------------- 1 | FORMAT: 1A 2 | HOST: http://omi.yourcompany.com/ 3 | 4 | # OMI API Specification - MVI 1.0 (beta) 5 | 6 | OMI is a non-profit initiative of leading academic institutions, music and media 7 | industry organizations, creators, technologists, entrepreneurs and policy experts 8 | who love and value music. 9 | 10 | The mission of the open music initiative is to promote and advance the development 11 | of open source standards and innovation related to music, to help assure proper 12 | compensation for all creators, performers and rights holders of music. 13 | 14 | New technologies can be applied to radically simplify the way music rights owners 15 | are identified and compensated, resulting in sustainable business models for artists, 16 | entrepreneurs and music businesses alike. 17 | 18 | We are committed to making change in the following areas: 19 | 20 | + Technology 21 | + Advocacy 22 | + Education 23 | + Policy 24 | 25 | This API is intended to be used by OMI members, by deploying a supporting implementation to somewhere like `http://omi.yourcompany.com/`. 26 | 27 | ## Scope of OMI 28 | 29 | This API is an informational draft for a minimal API that will provide a means for participants in the music ecosystem to share information about recordings, works, and their relationships in a relatively straightforward manner. The goal is to engender a degree of sharing through 'Minimal Viable Interoperability' through APIs that encourage a federated or distributed approach while not requiring ecosystem participants to given wholesale access to their data, or requiring registration in a centralized system. 30 | 31 | ## Version history 32 | 33 | + 2017-02-01 - draft v0.0.1 34 | + 2017-03-07 - draft v0.1 for OMI NY 35 | + 2017-06-22 - draft v0.2 beta release 36 | 37 | --------------------------------------- 38 | # Common API Conventions 39 | ## API Versioning 40 | 41 | The OMI Version is based on the common SemVer structure of a `major.minor.patch` version number string. 42 | Any changes in the `major` number might break backwards compatibility, `minor` changes should always be backwards compatible 43 | and `patch` level changes do not change the protocol or its content only descriptions, notes, etc in the documentation and 44 | therefor do not need to be passed in the request. 45 | 46 | Versioning of the OMI APIs is indicated by two mechanisms: headers and url prefixes. As a general principal, the prefix _must_ be supported by all conforming implementations. Implementations _may_ also include an `X-OMI-Version` header in the HTTP request and response. 47 | 48 | + Currently the version prefix is defined as `v1.0` 49 | + Currently the only supported value for the HTTP header is `1.0` 50 | 51 | ## Content Types 52 | 53 | As a general rule, all APIs produce JSON response data, defined by the appropriate schemas. The HTTP `Content-Type` header will be set to `application/json` and may include additional content type parameters, such as the character encoding, data version, etc. _TODO: Should we support something like `application/json+recording`_ 54 | 55 | All JSON object types will have a set of predefined fields with associated types defined, some of which will be optional. Implementations _must_ support the required fields, and _may_ support the optional fields. 56 | 57 | ### Extensions to standard types 58 | 59 | In addition to the defined properties, implementations _may_ include properties not defined within this specification. Such properties _should_ be marked as such: it is recommended that the extension properties be included as members of an outer `extensions` property as shown below: 60 | ``` 61 | { 62 | "name": "....", 63 | // Extension properties 64 | "ext": { 65 | "foo": { 66 | ... 67 | }, 68 | "bar": { 69 | ... 70 | } 71 | } 72 | } 73 | ``` 74 | It is also recommended that JSON mechanisms such as `@class` and `@type` be used to indicate the type and/or schema or extension properties. 75 | 76 | ## Authentication and Authorization 77 | 78 | Authentication and authorization are currently outside the scope of this document: it is imagined that many implementations of this API will be governed by business agreements and the access control will be at least partly dictated by the needs of the business. As a general rule, common web/HTTP based mechanisms, such as HTTPS, JWT token, OAuth etc. should be used in order to reduce the burden of integrations with the implementation. 79 | 80 | ## Query Language 81 | The query language supported by OMI is deliberately designed to be minimal, extensible, easily typed by humans, and to be easily encoded in URLs. It is deliberately very restricted in this first version and will be extended over time based upon demand from OMI members. 82 | 83 | HTTP queries are typically encoded in the URL with each query parameter, with a `name=value` syntax, separated by an `&`. OMI follow the same convention, with a few minor additions. The currently supported operators are listed below. 84 | 85 | | Operator | Meaning | 86 | |:-------------:|:-----------------------------:| 87 | | = | Equal to | 88 | | != | Not equal to | 89 | | & | Used to connect filters (and) | 90 | | * | Wildcard matching in values | 91 | 92 | This syntax is naturally encoded in URLs. For example, in order to search a collection of recording, for a given title and artist keyword, or to search via ISRC, one can do the following. 93 | ``` 94 | http://omi.yourcompany.com/recordings?title=Crystallize&artist=Stirling 95 | http://omi.yourcompany.com/recordings?isrc=US-TEY-09-00057 96 | ``` 97 | For objects that support arrays fields (such as `composers`) the corresponding field in a query would be the singular form (`composer`). 98 | 99 | As noted above, the query syntax is deliberately very restricted at this point in time, and does not allow for typical `and` and `or` queries: the ampersand symbol (`&`) is considered to mean `and` so the following query is a search for 'title and artist' 100 | ``` 101 | http://omi.yourcompany.com/recordings?title=Crystallize&artist=Sterling 102 | ``` 103 | In the case of objects that support fields that can have multiple values (`composers`) the `and` still applies, so while 104 | ``` 105 | http://omi.yourcompany.com/works?composer=Lindsey%20Sterling 106 | ``` 107 | will query for works by the composer 'Lindsey Stirling', the following will query for works that were a collaboration by 'Lindsey Stirling' and 'John Williams' (i.e. they both appear as composers for the work). 108 | ``` 109 | http://omi.yourcompany.com/works?composer=Lindsey%20Sterling&composer=John%20Williams 110 | ``` 111 | 112 | ### Wildcards and text matching 113 | 114 | As a general rule, OMI implementations _should_ support wildcard searches so that inexact matches can be made. Wildcard searches use the `*` symbol to indicate 'any number of additional characters'. As a general principal OMI implementations should perform matching in case insensitive way against the normal composed form (Unicode Normalization Form C). 115 | 116 | 123 | 124 | 125 | ### Data Structures 126 | 127 | ### Query Response (object) 128 | + count: 0 (number, required) - The number of results included in the response. 129 | + total: 0 (number, required) - The total number of results available. 130 | + offset: 0 (number, required) - The offset (starting from 0) within the total number of available results at which the result set starts. 131 | + results (array[Recording]) - The list of recordings. The size of the array will equal `count`. 132 | 133 | ### APIInformation 134 | + method: GET (string, required) 135 | + endpoint: /recording (string, required) 136 | + description: An API supporting... (string, optional) 137 | 138 | ### Attestor (object) 139 | + id: uuid:46166430-D1C6-4C00-9248-84B740FBE53D (string, required) - A unique identifier for the attestor 140 | + description: A random Oracle (string, optional) - A description of the attestor (usually used to indicate the algorithm, etc) 141 | 142 | ### Attestation (object) 143 | + attestor (Attestor, required) - Information about the attestor, which can be used to validate the provenance of the attestation. 144 | + created: 01/01/1970 00:02:16(string, required) - Timestamp indicating when the attestation was created in `MM/DD/YYYY HH:MM:SS format. 145 | + expires: 01/01/1970 00:02:16(string, optional) - Timestamp indicating when the attestation will expire in `MM/DD/YYYY HH:MM:SS format. 146 | + territory: usa (string, optional) - An ISO 3166 code indicating the territory an attestation is associated with. 147 | + confidence: 1.0 (number, optional) - The confidence level of the attestation, ranging from 0.0 (not confident) to 1.0 (absolute certainty). 148 | 149 | ### Album (object) 150 | + title: Lost in the moment (string, required) - The title of the album. 151 | + upc: 123456789012 (string, optional) - The UPC code of the album 152 | 153 | ### Recording (object) 154 | + title: Crystallize (string, required) - The title of the recording. 155 | + versionTitle: Crystallize Live Bonus Track (string, optional) - The title for a given version of the release. 156 | + alternateTitles (array[string], optional) - A list of alternative titles for the recording. 157 | + isrc: US-TEY-09-00057 (optional) - This is the primary way recordings should be identified. If the ISRC can be returned, it should be returned. 158 | + edited: false (boolean, optional) - A flag indicating the Edited/Explicit status 159 | + album (Album, optional) - The album in which the recording was released. 160 | + labels (array[Label], optional) 161 | + primary_artist (Artist, required) - Primary artist. 162 | + additional_artists (array[Artist], optional) - Additional features or guest artists. 163 | + released: 01/01/1970 (string, optional) - Date of the release for this version in `MM/DD/YYYY` format. 164 | + duration: 00:02:16 (string, optional) - The length of the recording in HH:MM:SS format. 165 | + territory:a (string, optional) - An ISO 3166 code indicating the territory a recording is associated with. 166 | 167 | ### Work (object) 168 | + title: Crystallize (string, required) - The title of the work. 169 | + alternateTitles (array[string], optional) - A list of alternative titles for the work. 170 | + titleSoundRecording (string, required) - The title of the sound recording for the work. 171 | + alternateTitleSoundRecording (array[string], optional) - A list of alternative titles of the sound recordings for the work. 172 | + iswc: US-TEY-09-00057 (string, optional) - The primary identitifer for a work. Where available this should be returned. 173 | + creators (array[CreatorAndSplit], required) 174 | + publishers (array[PublisherAndSplit], optional) 175 | + territory: usa (string, optional) - An ISO 3166 code indicating the territory a work is associated with. 176 | 177 | ### Person (object) 178 | + name: Lindsey Stirling (string, required) 179 | + contact: +1 123-456-7890 (string, optional) - A string holding contact information for the person. 180 | + territory usa (string, optional) - The territory associated with the person. The primary country of residence or registration as an ISO 3166 code. 181 | 182 | ### Artist (Person) 183 | + isni: 0000-0004-0314-2012 (string, optional) 184 | + primary: true (boolean, optional) - A flag indicating whether the Artist is the primary artist for a recording. 185 | + role: singer (optional) - The role of the artist 186 | 187 | ### Publisher (object) 188 | + name: Digital Empire (string, required) - The name of the publisher. 189 | + contact: +1 123-456-7890 (string, optional) - A string holding contact information for the publisher. 190 | 191 | ### PublisherAndSplit (Publisher) 192 | + split: 1.0 (number, optional) The percentage split the publisher receives. 193 | 194 | ### Creator (Person) 195 | + ipi: I-000000229-7 (string, optional) - The IPI number of the creator. 196 | + isni: 0000-0004-0314-2012 (string, optional) - This is the recommended identifier for work creators and should be supplied where available. 197 | + role: composer (string, optional) - The role of the creator 198 | + society: composer (string, optional) - The society the creator is affiliated with (for a given work). 199 | 200 | ### CreatorAndSplit (Creator) 201 | + split: 1.0 (number, optional) The percentage split the creator receives. 202 | 203 | ### Label (object) 204 | + id: uuid:46166430-D1C6-4C00-9248-84B740FBE53D (string, required) - The identifier for the label. 205 | + name: Sony Music (string, required) - The Label name. 206 | 207 | ### RecordingAndWorks (object) 208 | + recording (Recording, required) - The recording. 209 | + works (array[Work], required) - The possibly empty array of associated Work objects. 210 | + attestation (Attestation, required) - Attestation of the Recording to Works mapping. 211 | 212 | ### WorkAndRecordings (object) 213 | + work (Work, required) - The work. 214 | + recordings (array[Recording], required) - The possibly empty array of associated Recording objects. 215 | + attestation (Attestation, required) - Attestation of the Work to Recordings mapping. 216 | 217 | ### WorkContributors (object) 218 | + work (Work, required) - The work. 219 | + contributors (array[Person, Artist, Creator], required) - The possibly empty array of associated Recording objects. 220 | + attestation (Attestation, required) - Attestation of the Work to Recordings mapping. 221 | 222 | ### RecordingContributors (object) 223 | + recording (Recording, required) - The work. 224 | + contributors (array[Person, Artist, Creator], required) - The possibly empty array of associated Recording objects. 225 | + attestation (Attestation, required) - Attestation of the Work to Recordings mapping. 226 | 227 | 228 | ### APIQueryResponse (Query Response) 229 | + results (array[APIInformation], required) - The list of supported APIs. The size of the array will equal `count`. 230 | 231 | ### RecordingQueryResponse (Query Response) 232 | + results (array[Recording], required) - The list of recordings. The size of the array will equal `count`. 233 | 234 | ### WorkQueryResponse (Query Response) 235 | + results (array[Work], required) - The list of works. The size of the array will equal `count`. 236 | 237 | ### RecordingMappingQueryResponse (Query Response) 238 | + results (array[RecordingAndWorks], required) - The list of recording to work mappings. The size of the array will equal `count`. 239 | 240 | ### WorkMappingQueryResponse (Query Response) 241 | + results (array[WorkAndRecordings], required) - The list of work to recording mappings. The size of the array will equal `count`. 242 | 243 | # Group Recording Related APIs 244 | The group defines the APIs for manipulating collections of Recording objects. 245 | 246 | # Recording API Capabilities [/{version}/recordings/status] 247 | ## Query for supported APIs [GET] 248 | Query the status of the recording API supported by this implementation of the OMI API specification. The intent for this API is to also allow a degree of 'auto-discovery' of supported API features 249 | - A 404 (not found) response is returned if the implementation does not support any capabilities related to recordings. 250 | - A 200 response is returned if the implementation supports recording related APIs. Each entry in the response will contain an HTTP method and URL combination. 251 | + Headers 252 | 253 | X-OMI-Version: 1.0 254 | + Response 404 (application/json) 255 | + Response 200 (application/json) 256 | + Attributes (APIQueryResponse) 257 | 258 | # Recordings Collection [/{version}/recordings{%3Blimit}{%3Boffset}{?query_field}] 259 | 260 | ## Query for Recordings [GET] 261 | Query a collection of recordings and return the matching recording objects. This URL has a number of optional components: by default, leaving off the optional parameters will return the first _n_ recordings from the collection, where _n_ is defined by the implementation, but defaults to `10`. If no recordings matching the given (optional) criteria are found, an empty result set is returned, as shown below. 262 | ``` 263 | { 264 | "count": 0, 265 | "total": 0, 266 | "offset": 0, 267 | "results": [] 268 | } 269 | ``` 270 | The `limit` and `offset` parameters can be used to page over the recordings in the collection. For example, if limit is set to `10` (the default) and `limit` is set to `0`, then the results 0..9 will be returned. If `offset` is set to `10` results 10..19 will be returned. 271 | 272 | In the following example, an OMI implementation is being queried for recordings with the given ISRC code. 273 | ``` 274 | http://omi.yourcompany.com/recordings?isrc=US-TEY-09-00057 275 | ``` 276 | _Note: Currently the API does not define a means for sorting the results. This may be updated in a future revision._ 277 | + Parameters 278 | + version (string) 279 | The API version identifier. 280 | + query_field (optional, string) 281 | A filter to be applied to the recording collection in order to reduce the number of returned results. This can be used to find a recording by title and artist, for example. Please refer to the section on queries for the exact syntax to be used for queries. By default, only the standard fields of a recording can be filtered upon. 282 | + limit (optional, number) 283 | A limit on the number of objects to be returned. Limit can range 284 | between 1 and 1000 items. 285 | + Default: `10` 286 | + offset (number, optional) 287 | A offset into the recordings resource collection. 288 | + Default: `0` 289 | + Response 200 (application/json) 290 | + Headers 291 | 292 | X-OMI-Version: 1.0 293 | + Attributes (RecordingQueryResponse) 294 | 295 | ## Register a Recording [POST] 296 | Register a recording using the provided data. At a very minimum, the recording data _must_ include the required fields for a recording, but _may_ include the optional fields, and _may_ also provide optional extension fields. There is no guarantee that fields other than the required fields will be returned via queries, but it is strongly _recommended_ that implementations store and return the complete set of fields provided. 297 | + Headers 298 | 299 | X-OMI-Version: 1.0 300 | + Request (application/json) 301 | + Attributes (Recording) 302 | + Response 201 (text/plain) 303 | + Headers 304 | 305 | Location: URL to recording if direct linking is supported. 306 | + Body 307 | 308 | The recording was successfully registered. 309 | + Response 400 310 | + Body 311 | 312 | Bad request. The provided data is invalid. 313 | + Response 403 314 | + Body 315 | 316 | Forbidden. Not authorized to register recordings. 317 | + Response 409 318 | + Body 319 | 320 | Conflict. A recording matching the provided data already exists. 321 | 322 | # Recording to Works Mapping Collection [/{version}/recordings/works{%3Blimit}{%3Boffset}{?query_field}] 323 | 324 | ## Query for Works that match Recordings [GET] 325 | Query the collection of recordings and return works that are associated with the given recordings. 326 | ``` 327 | { 328 | "count": 0, 329 | "total": 0, 330 | "offset": 0, 331 | "results": [] 332 | } 333 | ``` 334 | In the following example, an OMI implementation is being queried for works that map to the recording with the given ISRC code. 335 | ``` 336 | http://omi.yourcompany.com/recordings/works?isrc=US-TEY-09-00057 337 | ``` 338 | _Note: Currently the API does not define a means for sorting the results. This may be updated in a future revision._ 339 | + Parameters 340 | + version (string) 341 | The API version identifier. 342 | + query_field (optional, string) 343 | A filter to be applied to the recording collection in order to reduce the number of returned results. This can be used to find a recording by title and artist, for example. Please refer to the section on queries for the exact syntax to be used for queries. By default, only the standard fields of a recording can be filtered upon. 344 | + limit (optional, number) 345 | A limit on the number of objects to be returned. Limit can range 346 | between 1 and 1000 items. 347 | + Default: `10` 348 | + offset (number, optional) 349 | A offset into the recordings resource collection. 350 | + Default: `0` 351 | + Response 200 (application/json) 352 | + Headers 353 | 354 | X-OMI-Version: 1.0 355 | + Attributes (RecordingMappingQueryResponse) 356 | 357 | # Recording to Contributors Mapping Collection [/{version}/recordings/contributors{%3Blimit}{%3Boffset}{?query_field}] 358 | 359 | ## Query for contributors that match Recordings [GET] 360 | Query the collection of works and return contributors that are associated with the given works. 361 | ``` 362 | { 363 | "count": 0, 364 | "total": 0, 365 | "offset": 0, 366 | "results": [] 367 | } 368 | ``` 369 | In the following example, an OMI implementation is being queried for contributors that map to the work by the given title. 370 | ``` 371 | http://omi.yourcompany.com/recordings/contributors?title=Purple%20Rain 372 | ``` 373 | _Note: Currently the API does not define a means for sorting the results. This may be updated in a future revision._ 374 | + Parameters 375 | + version (string) 376 | The API version identifier. 377 | + query_field (optional, string) 378 | A filter to be applied to the work collection in order to reduce the number of returned results. This can be used to find a work by composer for example. Please refer to the section on queries for the exact syntax to be used for queries. By default, only the standard fields of a work can be filtered upon. 379 | + limit (optional, number) 380 | A limit on the number of objects to be returned. Limit can range between 1 and 1000 items. 381 | + Default: `10` 382 | + offset (number, optional) 383 | A offset into the works resource collection. 384 | + Default: `0` 385 | + Response 200 (application/json) 386 | + Headers 387 | 388 | X-OMI-Version: 1.0 389 | + Attributes (RecordingContributors) 390 | 391 | # Group Work Related APIs 392 | The group defines the APIs for manipulating collections of Work objects. 393 | 394 | # Work API Capabilities [/{version}/works/status] 395 | ## Query for supported APIs [GET] 396 | Query the status of the work API supported by this implementation of the OMI API specification. The intent for this API is to also allow a degree of 'auto-discovery' of supported API features 397 | - A 404 (not found) response is returned if the implementation does not support any capabilities related to works. 398 | - A 200 response is returned if the implementation supports work related APIs. Each entry in the response will contain an HTTP method and URL combination. 399 | + Headers 400 | 401 | X-OMI-Version: 1.0 402 | + Response 404 (application/json) 403 | + Response 200 (application/json) 404 | + Attributes (APIQueryResponse) 405 | 406 | # Works Collection [/{version}/works{%3Blimit}{%3Boffset}{?query_field}] 407 | 408 | ## Query for Works [GET] 409 | Query a collection of works and return the matching works objects. This URL has a number of optional components: by default, leaving off the optional parameters will return the first _n_ works from the collection, where _n_ is defined by the implementation, but defaults to `10`. If no works matching the given (optional) criteria are found, an empty result set is returned, as shown below. 410 | ``` 411 | { 412 | "count": 0, 413 | "total": 0, 414 | "offset": 0, 415 | "results": [] 416 | } 417 | ``` 418 | The `limit` and `offset` parameters can be used to page over the works in the collection. For example, if limit is set to `10` (the default) and `limit` is set to `0`, then the results 0..9 will be returned. If `offset` is set to `10` results 10..19 will be returned. 419 | 420 | In the following example, an OMI implementation is being queried for works by the given composer. 421 | ``` 422 | http://omi.yourcompany.com/works?composer=Williams 423 | ``` 424 | _Note: Currently the API does not define a means for sorting the results. This may be updated in a future revision._ 425 | + Parameters 426 | + version (string) 427 | The API version identifier. 428 | + query_field (optional, string) 429 | A filter to be applied to the work collection in order to reduce the number of returned results. This can be used to find a work by composer for example. Please refer to the section on queries for the exact syntax to be used for queries. By default, only the standard fields of a recording can be filtered upon. 430 | + limit (optional, number) 431 | A limit on the number of objects to be returned. Limit can range between 1 and 1000 items. 432 | + Default: `10` 433 | + offset (number, optional) 434 | A offset into the works resource collection. 435 | + Default: `0` 436 | + Response 200 (application/json) 437 | + Headers 438 | 439 | X-OMI-Version: 1.0 440 | + Attributes (WorkQueryResponse) 441 | 442 | ## Register a Work [POST] 443 | Register a work using the provided data. At a very minimum, the work data _must_ include the required fields for a work, but _may_ include the optional fields, and _may_ also provide optional extension fields. There is no guarantee that fields other than the required fields will be returned via queries, but it is strongly _recommended_ that implementations store and return the complete set of fields provided. 444 | + Headers 445 | 446 | X-OMI-Version: 1.0 447 | + Request (application/json) 448 | + Attributes (Work) 449 | + Response 201 (text/plain) 450 | + Headers 451 | 452 | Location: URL to work if direct linking is supported. 453 | + Body 454 | 455 | The work was successfully registered. 456 | + Response 400 457 | + Body 458 | 459 | Bad request. The provided data is invalid. 460 | + Response 403 461 | + Body 462 | 463 | Forbidden. Not authorized to register works. 464 | + Response 409 465 | + Body 466 | 467 | Conflict. A work matching the provided data already exists. 468 | 469 | # Work to Recordings Mapping Collection [/{version}/works/recordings{%3Blimit}{%3Boffset}{?query_field}] 470 | 471 | ## Query for Recordings that match Works [GET] 472 | Query the collection of works and return recordings that are associated with the given works. 473 | ``` 474 | { 475 | "count": 0, 476 | "total": 0, 477 | "offset": 0, 478 | "results": [] 479 | } 480 | ``` 481 | In the following example, an OMI implementation is being queried for recordings that map to the work by the given composer. 482 | ``` 483 | http://omi.yourcompany.com/works/recordings?composer=Williams 484 | ``` 485 | _Note: Currently the API does not define a means for sorting the results. This may be updated in a future revision._ 486 | + Parameters 487 | + version (string) 488 | The API version identifier. 489 | + query_field (optional, string) 490 | A filter to be applied to the work collection in order to reduce the number of returned results. This can be used to find a work by composer for example. Please refer to the section on queries for the exact syntax to be used for queries. By default, only the standard fields of a work can be filtered upon. 491 | + limit (optional, number) 492 | A limit on the number of objects to be returned. Limit can range between 1 and 1000 items. 493 | + Default: `10` 494 | + offset (number, optional) 495 | A offset into the works resource collection. 496 | + Default: `0` 497 | + Response 200 (application/json) 498 | + Headers 499 | 500 | X-OMI-Version: 1.0 501 | + Attributes (WorkMappingQueryResponse) 502 | 503 | # Work to Contributors Mapping Collection [/{version}/works/contributors{%3Blimit}{%3Boffset}{?query_field}] 504 | 505 | ## Query for contributors that match Works [GET] 506 | Query the collection of works and return contributors that are associated with the given works. 507 | ``` 508 | { 509 | "count": 0, 510 | "total": 0, 511 | "offset": 0, 512 | "results": [] 513 | } 514 | ``` 515 | In the following example, an OMI implementation is being queried for contributors that map to the work by the given title. 516 | ``` 517 | http://omi.yourcompany.com/works/contributors?title=Purple%20Rain 518 | ``` 519 | _Note: Currently the API does not define a means for sorting the results. This may be updated in a future revision._ 520 | + Parameters 521 | + version (string) 522 | The API version identifier. 523 | + query_field (optional, string) 524 | A filter to be applied to the work collection in order to reduce the number of returned results. This can be used to find a work by composer for example. Please refer to the section on queries for the exact syntax to be used for queries. By default, only the standard fields of a work can be filtered upon. 525 | + limit (optional, number) 526 | A limit on the number of objects to be returned. Limit can range between 1 and 1000 items. 527 | + Default: `10` 528 | + offset (number, optional) 529 | A offset into the works resource collection. 530 | + Default: `0` 531 | + Response 200 (application/json) 532 | + Headers 533 | 534 | X-OMI-Version: 1.0 535 | + Attributes (WorkContributors) --------------------------------------------------------------------------------