RESTful API - handling updates that depend on other updates - javascript

I'm trying to design a RESTful API to serve data to a front-end JS app, and in future a native mobile app once I get round to writing it.
I'm fairly new to front-end dev, so API designs are also fairly new to me. I'm writing a table tennis league app to start my learning, and one of the endpoints doesn't seem to quite fit with any example I've read of recommended API structures.
I have two entities, leagues and players. A league has a collection of players, and when a result is entered the players switch "position" in the league if the winner was below the loser before the match was entered.
A standard REST API might have endpoints as follows to update the details of a specific player within the league:
(POST/PATCH) - /api/v1/leagues/{league-id}/players/{player-id}
e.g. /api/v1/leagues/1/players/12
This is fine, but in my case, when a result is entered into the web app, 2 different players need their "position" value updating via the API. Ideally, I would have this set as a unique field in the database, so only 1 player can be at each position within the league at any given time. However, if that were the case, using an API endpoint as above, my front-end app would need to calculate the new positions of the players based on the entered result, update player 1, and then if successful update player 2 (rolling back on failure). Following this structure, the position field cannot be made unique, as following the update of player 1, they both have the same position value until player 2 is updated.
The only other solution that I can think of is to have some other appropriately named endpoint that takes a "result" object, does the logic of working out the players new position on the server side, updates accordingly, and returns some data for the UI to re-bind and update to.
So my question is this: which of the 2 methods outlined above would you choose, and why?
If you choose the latter, what data would you return from the API call for the UI to bind to? A full league of player data? Or just the two players that have been updated?
Thanks

I think I see two problems
you haven't defined enough resources
you are confusing http with your domain model
Try something like this
PUT /api/v1/matches/{match-id}
{ winner : { id }, loser : { id }, ... }
Put to the API a message describing the outcome of the game (POST is acceptable, PUT is better for idempotency).
As a side effect of this message's arrival, incorporate the results into your domain model. It's your domain model that should include the rules that describe how the rankings of players change when a game is finished.
When somebody wants to see the rankings of the players...
GET /api/v1/leagues/{league-id}/standings
you send them to a resource that returns a representation of the current rankings in your model.
The spelling of the uri doesn't particularly matter; I prefer "standings" because I believe that's a real thing in your domain. But if you wanted to reflect the data structure of your resources without additional context, you might use a spelling like
GET /api/v1/leagues/{league-id}/players?orderBy=position
The data representation in the body of the request sent to you by the client isn't a serialization of an entity in your domain model, it's a serialization of a message addressed to your domain model.

The choice of where to calculate the positions within the league is really subjective - I would suggest doing it at the server, since it involves searching the database again (other players' scores).
Since you have multiple players and you may update 2 players at a time, it would be better to send the players' scores in the request body with their positions, and return the calculated full league information in the response for each request, because that would simplify your client code and ensure that you get the latest data.
This suggestion is based on the assumption that you do not have large number of players in a league (may be > 100). In that case, I would suggest approach 1 is better.
So your API URL can be..
(POST) /api/v1/leagues/{league-id}
And your request body, can be
"players":[
{"player-id":"101", "newScore":"10"},
{"player-id":"103","newScore":"20"}
]
Your response can be the full list of players in the resulting league.
"players":[
{"player-id":"101", "position":"1"},
{"player-id":"102", "position":"2"},
{"player-id":"103","position":"3"}
{"player-id":"104","position":"4"}
{"player-id":"105","position":"5"}
]

Related

Unsplash API: How to retrieve Access_Token for authenticated access-login by browser?

I needed to submit an approved-account access to Unsplash API, so as to access certain links for access approval. Given that the replies from the support team has taken more than a few days, I would just like to seek out additional help to resolve in retrieving the access_token for new requests-submissions via GET / POST methods.
The original website was working perfectly, till when I had wanted to get ready for submission for production stage and had wanted to prepare potential increases in requests to the Unsplash API.
However, the approval process entailed certain setup criterial, which I totally missed during my development phase and sought to iron out as soon as possible. One of the key component is to resolve your UTM links, which you may find here as the ideal reference: https://help.unsplash.com/en/articles/2511315-guideline-attribution.
My challenge then was that I had attempted to use the official javascript API, Unsplash-Javascript-API (https://github.com/unsplash/unsplash-js#authorization), in an effort to make the authentication / request processes simpler for my webapp to call.
Though most GET requests do work, given that a specific URL of links via "download_location" (https://help.unsplash.com/en/articles/2511258-guideline-triggering-a-download), has to be used instead, it will then require an authenticated request per new submission request by the webapp.
The final challenge then is that apparently it is not clear how the official Unsplash-Javascript-API actually pulls the "authenticated" request, as I was unable to find it on the website, so that I may retrieve the current-access_token for requests' usage.
The basic codes I am using via the API is the following, however I am confused what is the actual maximum request I may pull per page, I am hoping to get 100 returned images' details, but only gotten a maximum of 30 per time. Anyone can also help to confirm is there a workaround to increase this 30 to 100?
Retrieving a Collection of Photos
unsplash.collections.getCollectionPhotos(urlAPI, 1, 100, "Popular")
.then(toJson)
.then(jsonData => {
console.log("jsonData", jsonData);
});
So, currently my website is unable to launch for nearly 1 week plus, as I am just awaiting the final confirmation or additional help from the customer support end of the official Unsplash Team.
Hopeful that someone may help to assist me in clarifying the codes so that at least I can get one step closer to sorting this "official authenticated" process out, and take away one lesser step to getting my approval access for production ready.
Thank you in advance!
Given multiple tries. I wasn't able to retrieve the Access_Token reply, given that there is a pre-authorization step that I wasn't able to find any working solution to.
The current and clear limitations to the API are:
Maximum of 30 images request per GET request.
The official javascript API, Unsplash-Javascript-API (https://github.com/unsplash/unsplash-js#authorization) works but there is not clear or easy way to retrieve the "Access_Token" for a session usage.
Multiple async AXIOS / FETCH requests may not be "compiled successfully" when using ReactJS ContextProvider function prior to the first render. Therefore, an empty array will be shown instead on the final initial render.
Ultimately, my chosen solution is current to break down the images list to the most priority, with the limitation of only 30 images on retrieval, and still store into the original collection and retrieve it.
The other alternative is to actually download and load the images to your own server to load it, which may also be a faster route.
Sadly enough, the Unsplash API team doesn't response as frequently to assistance and my last contact was roughly 1 month ago, though I have attempted to update to their requirements but there were no feedback thereafter.
Thus, it will tentatively be better for you to just build an alternative solution than to rely on the team for a feedback, unless you are a paying client.
Good luck to the others on this! Cheers!

Limiting entries in Javascript Object

Alrighty! I'm working on small chat add-on for my website, and when a user logs on they'll see the chat history, I'm using a Javascript Object to store all messages in my NodeJS server, now I'd like it so whenever more than fifty entries are in the Object it adds the latest message and removes the oldest, I'd like this to limit my server from handling a lot of messages every time a user logs on. How would I be doing this?
Here's how I store my messages,
var messages = {
"session":[
]
};
messages.session.push(
{
"name":user.name,
"message":safe_tags_replace(m.msg),
"image":user.avatar,
"user":user.steamid,
"rank":user.rank,
}
);
I could also just do loading the last fifty messages in the JSON Object but whenever I run my server for a long time without restarting it this Object will become extremly big, would this be a problem?
Since you are pushing elements to the end of your array, you could just use array shift() to remove the first element of the array if needed. e.g.
var MAX_MESSAGES = 50;
if (messages.session.length > MAX_MESSAGES) { messages.session.shift(); }
To answer the second part of your question:
The more data you hold, the more physical memory you consume on the client machine, obviously. Which can - by itself - be a problem, especially for mobile devices and on old hardware. Also; having huge arrays will impact performance on lookup, iteration, some insert operations and sorting.
Storing JSON objects that contain chat history in the server is not a good idea. For one you are taking up memory that will be held up for an indefinite period. If you have multiple clients all taking to each other, these objects will continue to grow are eventually impact performance. Secondly once the server is restarted, or after your clenan up these objects, the chat history is lost.
The ideal solution is to store message in a database; a simple solution is mongoDB. Whenever a user logs in to the app. Query the db for that users chat history (here you can define how far back you want to go) and send them an initial response contain this data. Then whenever a message is sent, insert that message into the table/collection for future reference. This way the server is only responsible for sending chat history during the initial signon. After that the client is responsible for maintaining any added new message.

NodeJS + Socket IO Sends Too Much Data

I am currently developing a game using NodeJS + SocketIO but is having problem with the amount of data being sent. The server currently sends about 600-800 kbps which is not good at all.
Here are my classes:
Shape
Pentagon
Square
Triangle
Entity
Player
Bullet
Every frame (60 fps), I update each of the classes and each class will have an updatePack that will be sent to the client. The updatePack is pretty simple, it only containts the object's id and coords.
At first, I thought everyone's game are like that (silly me). I looked into several simple games like agar.io, slither.io, diep.io, and rainingchain.com and found that they use < 100 kbps which made me realize that I am sending too much data.
Then I looked into compressing the data being sent. But then I found out that data are automatically compressed when sending in Socket.io
Here is how I send my data:
for(var i in list_containing_all_of_my_sockets){
var socket = list_containing_all_of_my_sockets[i];
data = set_data_function();
socket.emit('some message', data);
}
How can I make it send less data? Is there something that I missed?
Opinionated answer, considering a way games handle server-client traffic. This is not the answer:
Rendering is a presentation concern. Your server, which is the single source of truth about the game state, should only care about changing and advertising the game state. 60fps rendering is not a server concern and therefore the server shouldn't be sending 60 updates per second for all moving objects (you might as well be better of just rendering the whole thing on the server and sending it over as a video stream).
The client should know about the game state and know how to render the changing game state at 60fps. The server should only send either state changes or events that change state to the client. In the latter case the client would know how to apply those events to change the state in tandem with the state known to the server.
For example, the server could be just sending the updated movement vectors (or even the acting forces) for each object and the client could be calculating the coordinates of each object based on their currently known movement vectors + the elapsed time.
Maybe its better not to send data every frame, but instead send it only on some particular events (etc. collisions,deaths,spawns)
Whenever a message is send over a network it not only contains the actual data you want to send but also a lot of additional data for routing, error prevention and other stuff.
Since you're sending all your data in individual messages, you'll create these additional information for every single one of them.
So instead you should gather all data you need to send, save it into one object and send this one in a single message.
You could use arrays instead of objects to cut down some size (by omitting the keys). It will be harder to use the data later, but... you've got to make compromises.
Also, by the looks of it, Socket.IO can compress data too, so you can utilize that.
As for updating, I've made a few games using Node.js and Socket.IO. The process is the following:
Player with socket id player1 sends his data (let's say coordinates {x:5, y:5})
Server receives the data and saves it in an object containing all players' data:
{
"player1": {x:5, y:5},
"player2": ...
...
}
Server sends that object to player1.
player1 receives the object and uses the data to visualize the other players.
Basically, a player receives data only after he has sent his own. This way, if his browser crashes, you don't bombard him with data. Otherwise, if you've sent 15 updates while the user's browser hanged, he needs more time to process these 15 updates. During that time, you send even more updates, so the browser needs even more time to process them. This snowballs into a disaster.
When a player receives data only after sending his own, you ensure that:
The sending player gets the other players' data immediately, meaning that he doesn't wait for the server's 60 times-per-second update.
If the player's browser crashes, he no longer sends data and therefore no longer receives it since he can't visualize it anyway.

RESTful API design with associations

I'm attempting to build an API for two resources, one with Users, and the other with Movies. Both resources have associations -- a User will have multiple Movies, and a Movie will have multiple Users. Presumably, I'd design my API something like this:
/api/users/
/api/users/:id
/api/users/:id/movies
/api/movies/
/api/movies/:id
/api/movies/:id/users
But here's the issue: I'm also using Backbone.js on the client side to fetch the API data. If If I create a Collection at
/api/users/:id/movies
then this will work well for GET requests, but POST and PUT requests would seemingly then be directed at:
/api/users/:id/movies/:id
But, seemingly, it would be better if it was posted to
/api/movies/:id
instead. Is that correct? How do people generally deal with RestFul associations?
Not sure what you mean by "POST and PUT requests would seemingly then be directed at...". Does Backbone.js automatically adds parameters to URLs? If so, you should look at configuring it so that it doesn't do that, because it won't be usable with a REST API. Links provided by a REST API should be the full ones, there's nothing to add or remove from them.
Finally, if you want to associate a movie with a user. You would POST the movie (or just its ID) to:
/api/users/:id/movies
It is correct. This is because "movies" are independent from "users". Movies can exist without users, so their relationship are actually "associative".
To create movies, you don't need users at all, so it makes more sense for the POST URI to create movie to be "POST /api/movies".
Alternative of association in RESTful API that I can think of is to have the list of movie IDs in the GET users API response, e.g. a property named "associatedMovieIDs" which has an array of strings of the IDs of the movies associated to the user.
With this, your APIs will then become:
/api/users/
/api/users/:id
/api/movies/
/api/movies/:id

Ways to save Backbone.js model data?

I am more into front end development and have recently started exploring Backbone.js into my app. I want to persist the model data to the server.
Could you please explain me the various way to save the Model data (using json format). I am using Java on server side. Also I have mainly seen REST being used to save data. As i am more into front end dev, i am not aware of REST and other similar stuff.
It would be great if someone could please explain me the process with some simple example.
Basically Models have a property called attributes which are the various values a certain model may have. Backbone uses JSON objects as a simple way to populate these values using various methods that take JSON objects. Example:
Donuts = Backbone.Model.extend({
defaults: {
flavor: 'Boston Cream', // Some string
price: '0.50' // Dollars
}
});
To populate the model there are a few ways to do so. For example, you can set up your model instance by passing in a JSON OR use method called set() which takes a JSON object of attributes.
myDonut = new Donut({'flavor':'lemon', 'price':'0.75'});
mySecondHelping = new Donut();
mySecondHelping.set({'flavor':'plain', 'price':'0.25'});
console.log(myDonut.toJSON());
// {'flavor':'lemon', 'price':'0.75'}
console.log(mySecondHelping.toJSON());
// {'flavor':'plain', 'price':'0.25'}
So this brings us up to saving models and persisting them either to a server. There is a whole slew of details regarding "What is REST/RESTful?" And it is kind of difficult to explain all this in a short blurb here. Specifically with regard to REST and Backbone saving, the thing to wrap your head around is the semantics of HTTP requests and what you are doing with your data.
You're probably used to two kinds of HTTP requests. GET and POST. In a RESTful environment, these verbs have special meaning for specific uses that Backbone assumes. When you want to get a certain resource from the server, (e.g. donut model I saved last time, a blog entry, an computer specification) and that resource exists, you do a GET request. Conversely, when you want to create a new resource you use POST.
Before I got into Backbone, I've never even touched the following two HTTP request methods. PUT and DELETE. These two verbs also have specific meaning to Backbone. When you want to update a resource, (e.g. Change the flavor of lemon donut to limon donut, etc.) you use a PUT request. When you want to delete that model from the server all together, you use a DELETE request.
These basics are very important because with your RESTful app, you probably will have a URI designation that will do the appropriate task based on the kind of request verb you use. For example:
// The URI pattern
http://localhost:8888/donut/:id
// My URI call
http://localhost:8888/donut/17
If I make a GET to that URI, it would get donut model with an ID of 17. The :id depends on how you are saving it server side. This could just be the ID of your donut resource in your database table.
If I make a PUT to that URI with new data, I'd be updating it, saving over it. And if I DELETE to that URI, then it would purge it from my system.
With POST, since you haven't created a resource yet it won't have an established resource ID. Maybe the URI target I want to create resources is simply this:
http://localhost:8888/donut
No ID fragment in the URI. All of these URI designs are up to you and how you think about your resources. But with regard to RESTful design, my understanding is that you want to keep the verbs of your actions to your HTTP request and the resources as nouns which make URIs easy to read and human friendly.
Are you still with me? :-)
So let's get back to thinking about Backbone. Backbone is wonderful because it does a lot of work for you. To save our donut and secondHelping, we simply do this:
myDonut.save();
mySecondHelping.save();
Backbone is smart. If you just created a donut resource, it won't have an ID from the server. It has something called a cID which is what Backbone uses internally but since it doesn't have an official ID it knows that it should create a new resource and it sends a POST request. If you got your model from the server, it will probably have an ID if all was right. In this case, when you save() Backbone assumes you want to update the server and it will send a PUT. To get a specific resource, you'd use the Backbone method .fetch() and it sends a GET request. When you call .destroy() on a model it will send the DELETE.
In the previous examples, I never explicitly told Backbone where the URI is. Let's do that in the next example.
thirdHelping = Backbone.Model.extend({
url: 'donut'
});
thirdHelping.set({id:15}); // Set the id attribute of model to 15
thirdHelping.fetch(); // Backbone assumes this model exists on server as ID 15
Backbone will GET the thirdHelping at http://localhost:8888/donut/15 It will simply add /donut stem to your site root.
If you're STILL with me, good. I think. Unless you're confused. But we'll trudge on anyway. The second part of this is the SERVER side. We've talked about different verbs of HTTP and the semantic meanings behind those verbs. Meanings that you, Backbone, AND your server must share.
Your server needs to understand the difference between a GET, POST, PUT, and DELETE request. As you saw in the examples above, GET, PUT, and DELETE could all point to the same URI http://localhost:8888/donut/07 Unless your server can differentiate between these HTTP requests, it will be very confused as to what to do with that resource.
This is when you start thinking about your RESTful server end code. Some people like Ruby, some people like .net, I like PHP. Particularly I like SLIM PHP micro-framework. SLIM PHP is a micro-framework that has a very elegant and simple tool set for dealing with RESTful activities. You can define routes (URIs) like in the examples above and depending on whether the call is GET, POST, PUT, or DELETE it will execute the right code. There are other solutions similar to SLIM like Recess, Tonic. I believe bigger frameworks like Cake and CodeIgniter also do similar things although I like minimal. Did I say I like Slim? ;-)
This is what excerpt code on the server might look (i.e. specifically regarding the routes.)
$app->get('/donut/:id', function($id) use ($app) {
// get donut model with id of $id from database.
$donut = ...
// Looks something like this maybe:
// $donut = array('id'=>7, 'flavor'=>'chocolate', 'price'=>'1.00')
$response = $app->response();
$response['Content-Type'] = 'application/json';
$response->body(json_encode($donut));
});
Here it's important to note that Backbone expects a JSON object. Always have your server designate the content-type as 'application/json' and encode it in json format if you can. Then when Backbone receives the JSON object it knows how to populate the model that requested it.
With SLIM PHP, the routes operate pretty similarly to the above.
$app->post('/donut', function() use ($app) {
// Code to create new donut
// Returns a full donut resource with ID
});
$app->put('/donut/:id', function($id) use ($app) {
// Code to update donut with id, $id
$response = $app->response();
$response->status(200); // OK!
// But you can send back other status like 400 which can trigger an error callback.
});
$app->delete('/donut/:id', function($id) use ($app) {
// Code to delete donut with id, $id
// Bye bye resource
});
So you've almost made the full round trip! Go get a soda. I like Diet Mountain Dew. Get one for me too.
Once your server processes a request, does something with the database and resource, prepares a response (whether it be a simple http status number or full JSON resource), then the data comes back to Backbone for final processing.
With your save(), fetch(), etc. methods - you can add optional callbacks on success and error. Here is an example of how I set up this particular cake:
Cake = Backbone.Model.extend({
defaults: {
type: 'plain',
nuts: false
},
url: 'cake'
});
myCake = new Cake();
myCake.toJSON() // Shows us that it is a plain cake without nuts
myCake.save({type:'coconut', nuts:true}, {
wait:true,
success:function(model, response) {
console.log('Successfully saved!');
},
error: function(model, error) {
console.log(model.toJSON());
console.log('error.responseText');
}
});
// ASSUME my server is set up to respond with a status(403)
// ASSUME my server responds with string payload saying 'we don't like nuts'
There are a couple different things about this example that. You'll see that for my cake, instead of set() ing the attributes before save, I simply passed in the new attributes to my save call. Backbone is pretty ninja at taking JSON data all over the place and handling it like a champ. So I want to save my cake with coconuts and nuts. (Is that 2 nuts?) Anyway, I passed in two objects to my save. The attributes JSON object AND some options. The first, {wait:true} means don't update my client side model until the server side trip is successful. The success call back will occur when the server successfully returns a response. However, since this example results in an error (a status other than 200 will indicate to Backbone to use the error callback) we get a representation of the model without the changes. It should still be plain and without nuts. We also have access to the error object that the server sent back. We sent back a string but it could be JSON error object with more properties. This is located in the error.responseText attribute. Yeah, 'we don't like nuts.'
Congratulations. You've made your first pretty full round trip from setting up a model, saving it server side, and back. I hope that this answer epic gives you an IDEA of how this all comes together. There are of course, lots of details that I'm cruising past but the basic ideas of Backbone save, RESTful verbs, Server-side actions, Response are here. Keep going through the Backbone documentation (which is super easy to read compared to other docs) but just keep in mind that this takes time to wrap your head around. The more you keep at it the more fluent you'll be. I learn something new with Backbone every day and it gets really fun as you start making leaps and see your fluency in this framework growing. :-)
EDIT: Resources that may be useful:
Other Similar Answers on SO:
How to generate model IDs with Backbone
On REST:
http://rest.elkstein.org/
http://www.infoq.com/articles/rest-introduction
http://www.recessframework.org/page/towards-restful-php-5-basic-tips

Categories