I have users and posts. Users can make posts. I am creating an endpoint for the posts. Does this make sense?
Posts
/posts - POST, create post
/posts?{uID} - GET, get posts for user
/posts?{pID} - GET, get post by id
/posts/{pID} - PUT, update post by id
Is this good design? It seems that both GET requests are too similar. Should I create something more distinct like:
/posts/users?{uID} - GET, get posts for user
Cons of the first: Additional logic on the backend (if else logic, to see which parameter was passed)
Cons of the second: Additional endpoint
I think most of your API design looks good, however you should change it slightly to follow the resource orientation suggested by the common API design guidelines:
/posts - POST, create post
/posts?userId={uID} - GET, get posts for user
/posts/{pID} - GET, get post by id
/posts/{pID} - PUT, update post by id
If you would like to have a nested structure rather than a query string to get all posts of a user, I would suggest to do the following instead of /posts/users?{uId}:
/users/{uId}/posts - GET, get posts for user
Related
How can I make certain parameters of the WordPress Rest API accessible to anyone without first being authenticated – for example, the page parameter doesn't work (where blog is a custom post type) in this query:
mysite.com/wp-json/wp/v2/blog?page=2&per_page=20
I've seen that in the past it's been possible to make these params available, for instance :
add_filter( 'json_query_vars', function( $valid_vars ) {
$valid_vars[] = 'offset';
return $valid_vars;
});
Is there any way to do something similar with today's version of the API?
For anyone who has the same problem, I've solved it. The page parameter is actually publicly available, offset is the one you need authentication for.
The reason the API didn't paginate was because the request url didn't have the paged query string set. Every time I tried to add it with the params option of the WordPress Node API, it didn't work:
wpapi.getNews().params('paged', 'paged').perPage( perPage ).page( pageNumber ).then(data=>
It didn't work because the request url created by the API seemed to always put the page parameter before the paged one, which resulted in paged being ignored when the query actually runs.
So in the end, I created a custom query (bit of a hacked way to do it, but it worked) like so:
Register the route:
wpapi.getNews = wpapi.registerRoute('wp/v2', '/news/(?P<customQuery>)');
Usage:
wpapi.getNews().customQuery('?paged&per_page=20&page='+pageNumber).then(data =>
Using the above, you can build any query, in any order you want. This helped me get the correctly paginated result. Also, we see 'getNews' here because I registered a route for accessing my custom post type called news.
Whenever I encounter code snippets on the web, I see something like
Meteor.subscribe('posts', 'bob-smith');
The client can then display all posts of "bob-smith".
The subscription returns several documents.
What I need, in contrast, is a single-document subscription in order to show an article's body field. I would like to filter by (article) id:
Meteor.subscribe('articles', articleId);
But I got suspicious when I searched the web for similar examples: I cannot find even one single-document subscription example.
What is the reason for that? Why does nobody use single-document subscriptions?
Oh but people do!
This is not against any best practice that I know of.
For example, here is a code sample from the github repository of Telescope where you can see a publication for retrieving a single user based on his or her id.
Here is another one for retrieving a single post, and here is the subscription for it.
It is actually sane to subscribe only to the data that you need at a given moment in your app. If you are writing a single post page, you should make a single post publication/subscription for it, such as:
Meteor.publish('singleArticle', function (articleId) {
return Articles.find({_id: articleId});
});
// Then, from an iron-router route for example:
Meteor.subscribe('singleArticle', this.params.articleId);
A common pattern that uses a single document subscription is a parameterized route, ex: /posts/:_id - you'll see these in many iron:router answers here.
Generally,the CRUD operation url pattern for model can be like this(Suppose the Model is Post):
new: /posts/new(get)
create:/posts/(post)
edit:/posts/edit(get)
update:/posts/1(put)
get:/posts/1(get)
However if there is a nested model "Comment".
And the association of the "Post" and "Comment" is one-many.
So what should the CURD operation url pattern like for comments ?
new: /posts/1/comments/new or /comments/new
create:?
edit:?
update:?
.......
What is the best practice?
Update:
It seems that the url for comment should be like this:
Get one comment for one post: /posts/1/comments/1
create: /posts/1/comments
update: /posts/1/comments/1
delete: /posts/1/comments/1
Now I am confused with the update and delete operation.
For update and delete: /posts/1/comments/1
SInce the comment id is specified,so I wonder if the /posts/1 inside the url is necessary?
I think the key is whether a comment is "contained" by the post resource. Remember that RESTful urls should be permalinks so under all of your scenarios, the end point to a specific comment(s) must not change. It sounds like it's containted so the url pattern can have the comment nested within the post. If that's not the case (e.g. a comment could move to another post which if nested would change the url) then you want a more flat structure with /comment/{id} urls referenced by the post resource).
The key is if it's a RESTful "Hypermedia API" then like the web it constantly links to the nested or referenced resources. It doesn't rely on the client necessarily understanding the REST pattern or special knowledge as to what end point holds the referenced or contained
resource.
http://blog.steveklabnik.com/posts/2012-02-23-rest-is-over
If a 'comment' is the resource(s) under a 'post' resource:
([httpVerb] /url)
get a post:
[get] /posts/{id}
body has a couple options - either it contains the full deep comments array
(depends on how much data, chat pattern)
{
id:xxx,
title:my post,
comments: [...]
}
... or it just contains the post resource with a url reference to the comments e.g.
{
id: xxx,
title: my post,
commentsUrl: /posts/xxx/comments
}
could also have an option like this (or other options to control depth):
[get] /posts/{id}?deep=true
get a collection of comments within a post:
[get] /posts/{id}/comments
returns 200 and an array of comments in the response body
create a comment for a post:
[post] /posts/{id}/comments
body contains json object to create
returns a 201 created
edit a comment under post:
[patch|post] /posts/{id}/comments/{id}
body contains json object with subset of fields/data to update
returns a 200
replace a post:
[put] /posts/{id}/comment/{id}
body contains json object to *replace*
returns a 200
If you have tons of comments per post, you could also consider a paging pattern:
{
id: xxx,
title: myPost,
pages:6,
commentsUrl:/posts/xxx/comments/page/1
}
then:
/posts/{id}/comments/pages/{pageNo}
{
nextPage: /posts/xxx/comments/2,
pages:7,
comments:
[ { ...,...,}]
}
each page would reference the next page, the page count and an array of comments for that page. If you went with a paging pattern then each comment in the array would have a reference url to the individual comment.
If you find yourself putting an action in the url, you're probably doing something wrong. Good read: http://blog.steveklabnik.com/posts/2011-07-03-nobody-understands-rest-or-http
You want to use the canonical URL for delete/update, which would be the complete one. More importantly, you shouldn't be exposing your Primary Key values which come from the Database as ids in the public api that is your restful URL space. These values could change in the future based on a database update, restore from backup, or anything else, depending on vendor. And you don't want an infrastructure change making all your URLs invalid if you can help it.
If you're using /posts/{postnum}/comments/{commentnum}, you can number the public comment ids starting from 1 for every post, making for shorter, nicer URLs.
I am using Linkedin REST API with PHP.
I am trying to get posts of a particular discussion group.
The API call is
http://api.linkedin.com/v1/groups/2417328/posts:(creation-timestamp,summary,title,type,comments,id,creator:(picture-url,last-name,headline,id,first-name,site-standard-profile-request))?count=100&start=0&modified-since=1312441200000
I would like to fetch the profile URL of the members who commented on each post also. Is it possible to do this with the above mentioned call?
Yes, it is possible - in the API call, specify the comment creator fields you would like to return from the list of available Profile Fields. To return the comment creator's profile URL, replace the comments Group Field with comments:(creator:(site-standard-profile-request)). You can specify other profile fields in there as needed.
I am designing a Restful HTTP API and have a design question.
In my application users should be able to suggest item creations.
Then I can either approve or disapprove them.
I wonder what the best VERB+URL pattern for this would be.
Example 1:
POST|GET|PUT|DELETE /items
A user POST a new item and I can either PUT it to "approved" from "pending" or DELETE it.
Here I must use GET /items?status=approved to get all approved items and GET /items?status=pending to get all pending items. Perhaps GET /items would get me all the approved ones by default.
But I don't get how I can prevent users from PUTting it to approved state.
or
Example 2:
POST|GET|PUT|DELETE /item_creation_suggestions
A user POST a new item suggestion and I can either approve by DELETE:ting it and do a POST /items or just DELETE it.
Here /items and /item_creation_suggestions are two separate collections. I just have to delete the suggestions and create the items when approving.
This makes it simple to protect my app from unauthorized access. I can just protect my /items with authorization, while /item_creation_suggestions could be used by anyone.
But this doesn't seem very Restful?
The same goes for when users are suggesting items updates and deletions and I either approve or disapprove them.
I am very new at Restful design so all feedback and suggestions would be appreciated!
The first one sounds good.
POST /items should create a new item and probably return a 202 Accepted status.
GET /items should return all approved items.
GET /items?status=pending should return pending items to users with the right permission.
PUT /items/[id] with a request body that designates a new status to change the status.
DELETE /items/[id] to delete the item.
In the end you need to decide what makes the most sense for your API, but the above sounds generally reasonable.
I'd also strongly prefer the first setup.
But I don't get how I can prevent users from PUTting it to approved state.
Your application logic needs to prevent users from POST'ing items with the approved state, if they don't have permission to do this. REST is not just a 'dead storage', you can actually process the request and throw a 403 Forbidden in case the user did something wrong.
Access control is still important and doesn't go against 'restfulness'.