I am having trouble getting my head around APIs.
Would someone have an example page that connects to the API and does something simple like display a username, that they would care to share?
A page showing this is something I could poke at, but I think sample code may work better. Which API are you looking at? OGS has two - REST and realtime. The REST API can do things such as retrieve user info, retrieve SGFs, start a challenge, examine games, provide authentication tokens for the realtime API, etc. (Take a look at the operations here for what is exposed to the REST interface.) The realtime (socket.io) API is a bit more complicated, and performs actions such as playing a game with immediately sending and receiving moves.
REST is a lot simpler than it may seem at first. All you’re doing is performing standard HTTP requests, just like your browser executed to retrieve this page. You can test it by simply clicking this link. That will execute a GET request against the API. Some requests require other HTTP verbs, primarily POST, which you cannot simply execute in a browser. Playing in Python will be your friend.
For how to do this in Python, take a look at using the Requests library. You can also use urllib2 as they show in the Apiary examples, but Requests is generally seen as simpler and better.
1 Like
Thanks for the reply! You can do POST with a form in http can’t you?
I haven’t used Python before, I had a fiddle with it the other day, but I couldn’t get it to work.
Yes, but you’ll have to navigate CORS (Cross-origin resource sharing - I think is what that stands for) if you’re going to go that route. Browsers have much stronger restrictions on sending POST requests to a domain that differs form the one you’re on. Since you can’t put your own form on online-go.com, you’ll have to execute a CORS request to make this work. This is a security measure to prevent a type of attack known as cross-site request forgery. (EDIT: I think forms still enforce this; I know POST requests through XMLHttpRequest do, but it’s possible a form would work without CORS.)
Python is a good intro coding language that lets you get up and running pretty quickly. I’d recommend starting with any of the hundreds of free tutorials to get a basic understanding and then go from there. Start with getting a Hello World example to work, and move up from there. Note that you’ll be spending a lot of time at a command prompt.
What languages are you familiar with? I recently wrote a Javascript (ES6) script that pulls user data from OGS given a username or ID, and stores it in local storage. IMO, the Fetch API in Javascript makes it really easy to make HTTP requests and then fiddle around with them, especially if you plan on working in a browser…
My original plan was to use javascript. Do you have an example you could share?
It’s pretty simple if you just want to fetch the data. I’m still working on the “sorting and displaying part” but getting the data is just a few lines of code. The core of it is basically
//Use something to point at the right domain/URL
//Saves bytes if we're doing lots on the same API, also easy to change.
const baseURL = "https://online-go.com/api/v1/players/"
var params = /*Anything you want to fetch, could be option like*/ "?ordering=username"
//Or a subdomain to fetch from, like /[insert userID]/games/
fetch (baseURL + params + "&format=json")
//This fetches the same stuff you'd get from going to the URL, and returns it as a promise
//You can handle it like
.then(response => {
if (!response.ok) { //Throws an error if HTTP fails
var error = new Error(response.statusText);
throw error;
}
return response.json(); //Converts to JS object
}
//Or you can declare that as a named function and just write in what the function's name is
//To use the variable, you can just keep on adding functions to the .then() chain.
//They will start executing after the previous one finishes, and be passed whatever it returns.
.then(thatDataWeFetched => {/*Do stuff with the data*/})
.catch(errors => {/*Handle any errors you might expect*/});
And that’s a basic fetch sequence. I’ve been testing with either a IDE (read: fancy text editor) or Node.js, so CORS hasn’t been an issue, but if you want to test using file:///, you can disable CORS by changing your request to fetch( URL, { mode: no-cors });. You can also do a POST request with fetch( URL, { method : POST });
I am going to answer my own question, in case it helps anyone else. Here is a html page with javascript that reads in the JSON data at https://online-go.com/api/v1/players and displays a value. In this case, the record count.
> <html>
> <body>
> <script type="text/javascript">
> function dofetch(urlAddress) {
> return fetch(urlAddress)
> .then(
> function(res) {
> return (
> res.json()
> );
> }
> );
> };
> function log(x){document.write(x.count)
> console.log(x)
> };
> dofetch("https://online-go.com/api/v1/players/?ordering=username&format=json").then(function(val){log(val);
> }
> );
>
> </script>
> </body>
> </html>