Comments (1)
tobowers
commented on August 15, 2024
curies for links
Let's take the people collection and the person object as references for how to use curies.
curies define the link type of a link (or list of links) and can be either global as defined here or application specific by using curies.
Let's assume for a second that we are using osdi as our curie prefix for links and let's take the person object's link section from here.
where it currently says:
"_links": {
"addresses": {
"href": "http://osdi-prototype.herokuapp.com/api/v1/people/23/addresses"
},
"question_answers": {
"href": "http://osdi-prototype.herokuapp.com/api/v1/people/23/question_answers"
},
"self": {
"href": "http://osdi-prototype.herokuapp.com/api/v1/people/23"
}
}it would become:
"_links": {
"self": {
"href": "http://osdi-prototype.herokuapp.com/api/v1/people/23"
},
"curies": [{ "name": "osdi", "href": "http://osdi-prototype.herokuapp.com/docs/rels/{rel}", "templated": true }],
"osdi:addresses": {
"href": "http://osdi-prototype.herokuapp.com/api/v1/people/23/addresses"
},
"osdi:question_answers": {
"href": "http://osdi-prototype.herokuapp.com/api/v1/people/23/question_answers"
}
}the curie is supposed to be a link type so let's take the addresses example and let's say we wanted to individually link from person... we could do that as such:
"_links": {
"self": {
"href": "http://osdi-prototype.herokuapp.com/api/v1/people/23"
},
"curies": [{ "name": "osdi", "href": "http://osdi-prototype.herokuapp.com/docs/rels/{rel}", "templated": true }],
"osdi:address": [{
"href": "http://osdi-prototype.herokuapp.com/api/v1/people/23/addresses",
"title": "home"
},{
"href": "http://osdi-prototype.herokuapp.com/api/v1/people/23/addresses",
"title": "work"
}],
"osdi:question_answers": {
"href": "http://osdi-prototype.herokuapp.com/api/v1/people/23/question_answers"
}
}The curie part of the links section is a way to construct links to documentation. It's actually perfectly valid to just drop a "coming soon" link in there
if you don't have docs.
"curies": [{ "name": "osdi", "href": "http://osdi-prototype.herokuapp.com/docs/coming_soon.html"}]Now you might say: "ok that's not much work, but what's the benefit?"
Well, the benefits are three fold.
- The curie can be used by the client to pick out which code should handle that link (think models)
- We have a baked in way of defining provider-specific links or links out to other APIs
- The client can now use templates to construct urls it'd otherwise have to know.
For number 3, let's take the People collection as an example.
{
"total_pages": 1,
"page": 1,
"total_records": 0,
"_embedded": {
"people": []
},
"_links": {
"self": {
"href": "http://osdi-prototype.herokuapp.com/api/v1/people"
},
"curies": [{ "name": "osdi", "href": "http://osdi-prototype.herokuapp.com/docs/rels/{rel}", "templated": true }],
"osdi:addresses": {
"href": "http://osdi-prototype.herokuapp.com/api/v1/addresses"
},
"osdi:find": { "href": "/people{?id}", "templated": true },
"osdi:filter": { "href": "/people{?odata_query}", "templated": true },
}
}Template syntax is defined here
Now, as a client, i can easily determine how to find a person by ID without having to just know the uri (a basic tenet of JSON+HAL).
Curies are also not very verbose and are human readable.
from osdi-docs.
Related Issues (20)
- Machine readable spec HOT 3
- We do not have a "general concepts document" with "more information about identifiers" HOT 1
- Advocacy Campaign Fields: change "target_list" to "targets" HOT 2
- Specify location based searches HOT 6
- Events should support more than one organizer HOT 4
- Autoresponse Trigger Params HOT 13
- Field for 501c[3|4] safety HOT 1
- OSDI Organizations Resource HOT 1
- RFC on extending Person resource for Organization use cases HOT 10
- helper action functions: Improper use of "improper subset"
- No open source license HOT 10
- spec is hand-wavey on how to use $expand to include additional properties/resources HOT 1
- Location searches are underspecified in ODATA HOT 4
- Cost efficient mappings to underlying APIs HOT 5
- TypeScript Definitions HOT 5
- @osdi scope on NPM HOT 7
- API Limit Metrics HOT 1
- Discovering Available Custom Fields HOT 1
- OSDI sandbox setup not working HOT 3
- Action Network's Coercion (was Response to PUT on api.opensupporter.org) HOT 18
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from osdi-docs.