REST API - non-static (changing) resource for single url - how to design? - rest

Imagine I have an API for a school. One of the resources is Department, which has various resources on it, such as a collection of Professors, and a "Head Professor".
Department looks like this:
{
"_links": {
"self": "http://myapi.com/department/math"
}
"name": "Math Department",
"headProfessor": {
"_links": {
"self": "http://myapi.com/professor/id/2",
"headProfessor": "http://myapi.com/headprofessor/department/math"
},
"name": "George Patton",
"id": "2"
}
"professors": {
"_links": {
"self": "http://myapi.com/professors/department/math"
},
"_collectionData": [
{
"_links": {
"self": "http://myapi.com/professor/id/1"
},
"name": "John Doe",
"id": "1"
},
{
"_links": {
"self": "http://myapi.com/professor/id/2"
},
"name": "George Patton",
"id": "2"
},
{
"_links": {
"self": "http://myapi.com/professor/id/3"
},
"name": "Paul Simon",
"id": "3"
}
]
}
}
My question is regarding "headProfessor" and the links. What is the canonical link for the "head professor"? Is it http://myapi.com/professor/id/1 or is it http://myapi.com/headprofessor/department/math? Should I have both in there? Or is only one necessary? Is there a better way to represent the "head" or the "top" of something, basically a url whose resource could change because it represents a relationship and not a static resource?
NOTE
Yes, I do prefer the resource designator first in the url as it gives the resource designator the same location in every url. But my question is not about that. That's just a matter of taste and style.

First of all Department has professors and not vice-versa so your APIs should be designed like this
http://myapi.com/departments -> GET all departments
http://myapi.com/departments/{departmentId}/professors ---> POST to add a professor to a department , body of POST has the rank of professor has HOD, or staff
http://myapi.com/departments/{departmentId}/professors ---> GET should get all professors of that department
http://myapi.com/departments/{departmentId}/professors?rank=hod ---> Should give you the HOD
http://myapi.com/departments/{departmentId}/professors/{professorId} ---> PUT to change rank of Professor
http://myapi.com/departments/{departmentId}/professors/{professorId} ---> DELETE to remove professor from Department if he retires or moves to another college,etc.

Related

How to create a jsonpath to instagram business account in a batch request with the Graph API?

My goal is to create a batch request with dependent calls as documented here:
https://developers.facebook.com/docs/graph-api/making-multiple-requests#operations
You can reference the results of a previous operation using JSONPath in form post parameters in addition to query string parameters.
I can't get the right JSONPath to make it work when there are multiple elements in the data array that have an instagram_business_account.id (iba_id)
The two calls that I want to make are
/me/accounts?fields=instagram_business_account
/17841400714813297?fields=business_discovery.username(thomasguntenaar){media_count}
my batch looks like
[
{"method":"GET","name":"get-ig", "relative_url":"me/accounts?fields=instagram_business_account"},
{"method":"GET", "relative_url":"{result=get-ig:$.data..instagram_business_account.id}?fields=business_discovery.username(thomasguntenaar){media_count}}"}
]
in the second query you are supposed to put the JSONPath to the instagram business account id
after result=
I get this error back
{
"code": 404,
"body": "{
\"error\": {
\"message\": \"(#803) Some of the aliases you requested do not exist: 17841400714813297,17841403388404550,17841401383243593\",
\"type\": \"OAuthException\",
\"code\": 803,
\"fbtrace_id\": \"FV8qA+oA7fp\"
}
}"
}
Facebooks json response after the first call is
{
"data": [
{
"id": "466912700123917"
},
{
"id": "502655553273897"
},
{
"instagram_business_account": {
"id": "17841400714813297"
},
"id": "503124266815195"
},
{
"instagram_business_account": {
"id": "17841403388404550"
},
"id": "510613645695833"
},
{
"instagram_business_account": {
"id": "17841401383243593"
},
"id": "2061834074114937"
}
],
"paging": {
"cursors": {
"before": "NDY2OTEyNzAwMTIzOTE3",
"after": "MjA2MTgzNDA3NDExNDkzNwZDZD"
}
}
}
When you query the second request like this
?ids=17841400714813297,17841403388404550,17841401383243593&fields=business_discovery.username(thomasguntenaar){username,media_count}
the response looks like this
{
"17841400714813297": {
"business_discovery": {
"username": "thomasguntenaar",
"media_count": 76,
"id": "17841400714813297"
},
"id": "17841400714813297"
},
"17841403388404550": {
"business_discovery": {
"username": "thomasguntenaar",
"media_count": 76,
"id": "17841400714813297"
},
"id": "17841403388404550"
},
"17841401383243593": {
"business_discovery": {
"username": "thomasguntenaar",
"media_count": 76,
"id": "17841400714813297"
},
"id": "17841401383243593"
}
}
(#803) Some of the aliases you requested do not exist: 17841400714813297,17841403388404550,17841401383243593
Apparently the API thinks this was supposed to be one id, and doesn’t realize it is supposed to be three separate ones.
The API has a syntax to request data for more than one object in one request - instead of /{id}?fields=foo, you can make a request of the form ?ids={1,2,3}&fields=foo, to request this data for the objects with ids 1, 2 and 3 in one go. The resulting data structure will contain a sub-structure for each of those ids.
The same structure should work in batch requests as well, when parts (here, the IG account ids returned by the previous query) are dynamically inserted.

ACRCloud external meta data and IDs not returning

When making valid requests to http://ap-southeast-1.api.acrcloud.com/v1/identify I get successful responses, however both external_ids and external_metadata always come back as empty objects.
Example response:
{
"external_ids": {},
"play_offset_ms": 97480,
"external_metadata": {},
"label": "Universal Music Ltd.",
"release_date": "2012-01-01",
"album": {
"name": "The Love Club EP"
},
"title": "Royals",
"duration_ms": "190185",
"genres": [
{
"name": "Pop"
}
],
"acrid": "b748d828aba29c699f732bd660123bae",
"result_from": 3,
"artists": [
{
"name": "Lorde"
}
]
}
Anyone know why all my identifications wouldn't contain this data?
Please select the 3rd party ID integration while creating the projects.

REST and many to many

I'm basing my question on How to handle many-to-many relationships in a RESTful API? but want to continue from the accepted answer.
Let's suppose we have a many-to-many relationship between players and teams (just like in the question mentioned above).
As I understand it, there are several options to model this with REST resources:
The payload contains references to the related resources
GET /players/john
yields
{
"name": "John",
"_links": [
{
"rel": "team",
"href": "/teams/1"
},
{
"rel": "team",
"href": "/teams/4"
}
]
}
and
GET /teams/1
yields
{
"name": "Team 1",
"_links": [
{
"rel": "player",
"href": "/players/john"
},
...
]
}
This forces me to update a player-resource when I just want to add a player to the team. Furthermore, when I add a player to the team using a player-resource, the corresponding team-resource gets automatically updated. According to How to handle many-to-many relationships in a RESTful API?:
you don't want the alternate URL /players/5/teams/ to remain cached
In this case, teams/1 might remain cached when I update player "John" to remove team "Team 1" from it!
The relationship is modelled as another resource
GET /teams/1
yields
{
"name": "Team 1",
}
and
GET /players/john
yields
{
"name": "John",
}
Finally,
GET /relationships
yields
[
{
"_links": [
{
"rel": "player",
"href": "/players/john"
},
{
"rel": "team",
"href": "/teams/1"
}
]
},
...
]
This way, I can create and delete relationships without affecting both player-resources and team-resources. But when I delete /players/john, should the matching relationships be automatically deleted as well? If this is the case, the same rule as above is violated. If this is not the case we need the manually delete these relationships which is a lot of work I do not want to burden the consumers of my API with.
Furthermore, if we want to update the teams a certain player "John" is in, we need to delete some relationships and add others. We open ourselves up to merge conflicts (and race conditions) when someone else is editing the player "John" or the team "Team 1".
Each side of the relationship gets its own relationship-object
GET /teams/1/players
yields something like
{
"_links": [
{
"rel": "player",
"href": "/players/john"
},
...
]
}
and
GET /players/john/teams
something like
{
"_links": [
{
"rel": "team",
"href": "/teams/1"
},
...
]
}
But adding or removing one might still affect a resource that is located at a different URL (which does not share a root element)
My questions
Is there away around the problems I have mentioned in both cases?
Which of both approaches is 'preferable' or more pure REST?
How serious should I take the contstraint mentioned in How to handle many-to-many relationships in a RESTful API?:
you don't want the alternate URL /players/5/teams/ to remain cached
Thank you in advance!
You could have the following
Team
GET /teams/dream
{
"_links": {
"self": {
"href": "/teams/dream"
}
"players": {
"href": "/players?team=dream"
}
},
"name": "Dream"
}
Player
GET /player/john
{
"_links": {
"self": {
"href": "/player/john"
},
"teams": {
"href": "/teams?player=john"
},
},
"name": "John",
}
John's teams
GET /teams?player=john
{
"_links": {
},
"items": [
{
"href": "/teams/a-team"
}
],
}
Adding john to dream team, (using json patch for example) (query string on patch post...etc though rare, is valid)
PATCH /teams?player=john
[{
"op": "add",
"path": "/-",
"value": {
"href": "/team/dream"
}
}]
Get john's teams
GET /teams?player=john
{
"_links": {
},
"items": [
{
"href": "/teams/a-team"
},
{
"href": "/teams/dream"
}
]
}
John leaves A Team :
PATCH /teams?player=john
[{
"op": "remove",
"path": "/0"
}]

How can I query an indexed object list in mongodb?

I have some documents in the "company" collection structured this way :
[
{
"company_name": "Company 1",
"contacts": {
"main": {
"email": "main#company1.com",
"name": "Mainuser"
},
"store1": {
"email": "store1#company1.com",
"name": "Store1 user"
},
"store2": {
"email": "store2#company1.com",
"name": "Store2 user"
}
}
},
{
"company_name": "Company 2",
"contacts": {
"main": {
"email": "main#company2.com",
"name": "Mainuser"
},
"store1": {
"email": "store1#company2.com",
"name": "Store1 user"
},
"store2": {
"email": "store2#company2.com",
"name": "Store2 user"
}
}
}
]
I'm trying to retrieve the doc that have store1#company2.com as a contact but cannot find how to query a specific value of a specific propertie of an "indexed" list of objects.
My feeling is that the contacts lists should not not be indexed resulting in the following structure :
{
"company_name": "Company 1",
"contacts": [
{
"email": "main#company1.com",
"name": "Mainuser",
"label": "main"
},
{
"email": "store1#company1.com",
"name": "Store1 user",
"label": "store1"
},
{
"email": "store2#company1.com",
"name": "Store2 user",
"label": "store2"
}
]
}
This way I can retrieve matching documents through the following request :
db.company.find({"contacts.email":"main#company1.com"})
But is there anyway to do a similar request on document using the previous structure ?
Thanks a lot for your answers!
P.S. : same question for documents structured this way :
{
"company_name": "Company 1",
"contacts": {
"0": {
"email": "main#company1.com",
"name": "Mainuser"
},
"4": {
"email": "store1#company1.com",
"name": "Store1 user"
},
"1": {
"email": "store2#company1.com",
"name": "Store2 user"
}
}
}
Short answer: yes, they can be queried but it's probably not what you want and it's not going to be really efficient.
The document structure in the first and third block is basically the same - you have an embedded document. The only difference between are the name of the keys in the contacts object.
To query document with that kind of structure you will have to do a query like this:
db.company.find({ $or : [
{"contacts.main.email":"main#company1.com"},
{"contacts.store1.email":"main#company1.com"},
{"contacts.store2.email":"main#company1.com"}
]});
This query will not be efficient, especially if you have a lot of keys in the contacts object. Also, creating a query will be unnecessarily difficult and error prone.
The second document structure, with an array of embedded objects, is optimal. You can create a multikey index on the contacts array which will make your query faster. The bonus is that you can use a short and simple query.
I think the easiest is really to shape your document using the structure describe in your 2nd example : (I have not fixed the JSON)
{
"company_name": "Company 1",
"contacts":{[
{"email":"main#company1.com","name":"Mainuser", "label": "main", ...}
{"email":"store1#company1.com","name":"Store1 user", "label": "store1",...}
{"email":"store2#company1.com","name":"Store2 user", "label": "store2",...}
]}
}
like that you can easily query on email independently of the "label".
So if you really want to use the other structure, (but you need to fix the JSON too) you will have to write more complex code/aggregation pipeline, since we do not know the name and number of attributes when querying the system. Theses structures are also probably hard to use by the developers independently of MongoDB queries.
Since it was not clear let me show what I have in mind
db.company.save(
{
"company_name": "Company 1",
"contacts":[
{"email":"main#company1.com","name":"Mainuser", "label": "main"},
{"email":"store1#company1.com","name":"Store1 user", "label": "store1"},
{"email":"store2#company1.com","name":"Store2 user", "label": "store2"}
]
}
);
db.company.save(
{
"company_name": "Company 2",
"contacts":[
{"email":"main#company2.com","name":"Mainuser", "label": "main"},
{"email":"store1#company2.com","name":"Store1 user", "label": "store1"},
{"email":"store2#company2.com","name":"Store2 user", "label": "store2"}
]
}
);
db.company.ensureIndex( { "contacts.email" : 1 } );
db.company.find( { "contacts.email" : "store1#company2.com" } );
This allows you to store many emails, and query with an index.

How to retrive action ID with object ID and User ID? (Open Graph Custom Action)

So the situation is such:
I want the user to perform an (unique) action on my page. I do this through the presentation of an interface and a set of objects on my page. Works flawlessly.
But in order to present a complete user interface I must also give the option to delete the performed action, so I must know if a user has already interacted with a certain object.
Now could I run through all the objects, the user has interacted with and check, if the asked object is in there, but this way is not very resource savvy, when the user has interacted with a lot of items.
So the basic question is: Is there an API method, where I can look whether this user has already an action with the given object?
Thanks for your help!
https://graph.facebook.com/me/APP_NAMESPACE:ACTION_NAME
This will give you a list of all the actions of type ACTION_NAME that the current user has performed.
In the list you'll also find the connected objects.
Example:
https://graph.facebook.com/me/polarprint_forum:ask
{
"data": [
{
"id": "10150663311283415",
"from": {
"id": "549348414",
"name": "Joakim Syk"
},
"start_time": "2012-03-08T13:10:44+0000",
"end_time": "2012-03-08T13:10:44+0000",
"publish_time": "2012-03-08T13:10:44+0000",
"application": {
"id": "346637838687298",
"name": "Polar Print Forum"
},
"data": {
"question": {
"id": "10150604589861693",
"url": "http://www.polarprint.se/facebook_thread_tab/946/k\u0025C3\u0025A4ppteknik_vid_kullersten.html",
"type": "polarprint_forum:question",
"title": "käppteknik vid kullersten"
}
},
"likes": {
"count": 0
},
"comments": {
"count": 0
}
}
],
"paging": {
"next": "https://graph.facebook.com/me/polarprint_forum:ask?format=json&offset=25&limit=25"
}
}
A more efficient approach would probably be to store this information on your end when creating the actions.