REST API Архитектура и стандарты

Архитектура REST API architectureбыла hasсоздана, beenчтобы createупростить toи makeстандартизировать theпроцедуры proceduresдоступа toк accessданным dataиз fromразличных different services easier and more standardized.служб.

ThisЭта logicalлогическая architectureархитектура frequentlyчасто usesиспользует jsonструктуру data structure to send and receive data.данных JSON isдля anотправки openи standardполучения fileданных. formatJSON and— dataэто interchangeоткрытый formatстандартный thatформат usesфайла human-readableи textформат toобмена storeданными, andв transmitкотором dataдля objectsхранения consistingи ofпередачи attribute–valueобъектов pairsданных, andсостоящих arrays.из пар атрибут-значение и массивов, используется удобочитаемый текст.

JsonПример dataданных example:JSON:

{ 
	"api": "v2.7",
    "apipath": "https://www.rackcorp.net/api/v2.7"
    }

ThisЭти dataданные couldмогут beбыть representedпредставлены asв anвиде arrayмассива orили objectобъекта inна manyмногих languagesязыках, suchтаких asкак PHP,  PYTHON andи C#C#.

Rackcorp hasперенесла migratedмногие manyиз ofсвоих itsфункций functionalitiesдля toработы workс withархитектурой REST APIAPI, architectureчтобы toмодернизировать modernizeи andупростить makeпроцесс easyполучения theданных processпо toпротоколу getHTTP. dataКаждый throughмесяц HTTPмы protocol.добавляем Everyновые monthсервисы we are adding new services throughчерез REST API. ItВажно, isчтобы importantвы youподписались followна usнас, toчтобы getполучать theпоследние lastобновления updatesи andпоследнюю theверсию last version of ourнашего API.

SomeНекоторые importantважные concept ofконцепции REST API:

• методы HTTP methods - GET, POST, PUT, DELETE

WebВеб-разработчики, developersвероятно, areзнакомы likely familiar withс GET andи POST, alongа withтакже theс otherдругими HTTPметодами methods,HTTP, alsoтакже sometimesиногда calledназываемыми HTTPHTTP-глаголами. verbs.Эти Theseметоды methodsопределяют defineтип theзапроса type of request being made to aк REST API. 

• MethodsМетоды byпо use:использованию:
  • GET - requestзапросить dataданные
  • POST - insertвставить newновые dataданные
  • PUT - updateобновить dataданные
  • DELETE - deleteудалить dataданные

• ResourceИмена Names:ресурсов:

Resources are sometimes referred to as the nouns that the HTTP verbs act upon. Earlier web services were built around        remote procedure calls, which saw APIs as extensions of the code that called them. By contrast, REST resources can be accessed with multiple HTTP methods. 

Ресурсы иногда называют существительными, на которые воздействуют HTTP-глаголы. Ранее веб-службы были построены на основе удаленных (на дистанции) вызовов процедур, в которых API рассматривались как расширения вызывающего их кода. Напротив, к ресурсам REST можно получить доступ с помощью нескольких методов HTTP.

• • GET /api/animals: retrieve aполучить listсписок of animalsживотных.
  • POST /api/animals: add aдобавить newновое animalживотное
  • GET /api/animals/dog: retrieve aполучить singleодно animalживотное byпо IDидентификатору ID.
  • PUT /api/animals/dog: update aобновить singleодно animalживотное byпо IDидентификатору ID.
  • DELETE /api/animals/dog: delete anудалить animalживотное byпо IDидентификатору ID.

• DataФорматы Formats:данных:

MostБольшинство запросов API requestsбудут willвозвращать returnс contentсервера fromсодержимое, theкоторое serverклиент thatдолжен theинтерпретировать. clientРедко needsэто toсодержимое interpret.представляет Rarelyсобой isобычный thisтекст content— plainобычно text—usually,оно itиспользует willформат useструктурированных aданных. structured data format. WhileХотя REST doesне notопределяет specifyкакие-либо anyформаты dataданных, formats,чаще всего используются JSON andи XML are the two most commonly used.XML.

Json:JSON:

{
  "id": "dog",
  "name": "Pet dog",
  "genus": "Canis",
  "img": "https://cdn2.thedogapi.com/images/1MZ0YbOpS.jpg"
}

Xml:XML:

<?xml version="1.0" encoding="UTF-8" ?>
<root>
  <id>dog</id>
  <name>Domestic dog</name>
  <genus>Canis</genus>
  <img>https://cdn2.thedogapi.com/images/1MZ0YbOpS.jpg
</img>
</root>

• HTTPСтатусы Statuses:HTTP:

SinceПоскольку API-интерфейсы REST APIsзависят dependот uponстандартов HTTPHTTP, standards,статус eachкаждого request’sзапроса statusиспользуется isдля usedсообщения toрезультата communicateзапроса, theтакого resultкак ofуспех theили request,неудача. suchКаждый asкод successсостояния orпредоставляет failure.машиночитаемый Eachответ, statusа codeтакже providesсообщение, aпонятное machine-readableчеловеку. response, plus a human-readable message. Web developersВеб-разработчики (andи aряд numberпользователей) ofзнакомы users)со willмногими beиз familiar with many of these.них.

• • 200: SuccessУдачный (Success)
  • 201: CreatedСоздан (Created)
  • 401: UnauthorizedНеавторизирован (Unauthorized)
  • 403: ForbiddenЗапрещен (Forbidden)
  • 404: Не найден (Not foundfound)
  • 429: Слишком много запросов (Too many requestsrequests)

WhileХотя REST isне notявляется aстандартом, standard,существует thereмножество areдругих manyстандартов, otherчасто standardsсвязанных often associated withс REST. For example,Например, OAuth coversохватывает third-partyстороннюю authorizationавторизацию forресурсов, resources whileа JSON PATCH describesописывает aстандартный standardподход approachк to theметоду HTTP PATCH methodдля forформата theданных JSONJSON. dataВажным format.стандартом, Anо importantкотором standardследует toпомнить keepпри inразработке mindсобственных asAPI, youявляется designспецификация your own APIs is the OpenAPI specification.OpenAPI.

HowКак toсделать make aзапрос REST API requestдля toполучения, get,вставки insertи andобновления update data?данных?

YouВы canможете make aсоздать REST APIAPI, usingиспользуя anyлюбой programmingязык languageпрограммирования, suchтакой asкак Javascript, PHP, PYTHON andи C#. InВ thisэтой articleстатье weмы willдобавим addнесколько someпримеров samplesкода, ofчтобы codeобъяснить, toкак explainсделать howзапрос toс make a request usingпомощью Javascript (JQUERY) andи PHP. WeМы chooseвыбрали theseэти twoдва languagesязыка, becauseпотому itчто isэто mostони popularсамые languageпопулярные toдля deployразвертывания a website.веб-сайтов.

WeМы stronglyнастоятельно recommendрекомендуем onlyвыполнять makeвызовы REST API callsтолько fromдля yourбэкэнда. back-endБудьте code,осторожны beпри carefulиспользовании when useкода javascript codeдля toвызова call aURL-адреса REST APIAPI. url.Никогда Neverне addдобавляйте yourсвои credentialsучетные inданные front-endво code.фронтъенд.

Javscript (JQUERY):

Firstly,Во-первых, youВам needнужно toсоздать createнебольшую aлогику smallдля logicвызова toURL-адреса callAPI theв apiкачестве urlпримера as the sample bellow:ниже:

<script>
let query = {};
const v = 'v2.7';
const URL = 'https://www.rackcorp.net/api/'+v+'/dcs';
$.ajax({
	ur: URL,
    type: 'GET',
    data: query,
    success: function(res) {
        console.log(res);
        alert(res);
    },
    error: function(res) {
    	console.log(res);
        alert(res);
    }
});
</script>
    

You can see that the code to make requests using REST API is quite simple.

We have a variable called 'data' which is the object which would contain the pair of key-values which will be translate into a query in back-end. Them, we create a string variable which is the URL to connect to the REST API HTTP. With this two variables, we are able to create the AJAX script to call the REST API. If the code is correct, the logic will redirect to SUCCESS, if the code is wrong it will redirect to ERROR. Them, you can treat the response ('rest') as you wish.

Be careful to use javascript to make REST API requests. It is because javascript is a front-end programming language, it means the code runs in the user desktop (notebook, phones) and this code can be intercepted by hackers and any other malicious person. REST API requests in javascript is only recommended when you dont need to pass sensitive data, like keys, password or personal information. In the sample above, we called an URL to list all Data Centers (DC) in Rackcorp which doesnt need authentication, it is open to the world.

Вы можете видеть, что код для выполнения запросов с использованием REST API довольно прост.

У нас есть переменная с именем «данные», которая представляет собой объект, который будет содержать пару «ключ-значение», которая будет преобразована в запрос в бэкэнде. Затем мы создаем строковую переменную, которая является URL-адресом для подключения к REST API HTTP. С помощью этих двух переменных мы можем создать сценарий AJAX для вызова REST API. Если код правильный, логика перенаправит к УСПЕХУ, если код неправильный, он перенаправит к ОШИБКЕ. Вы можете относиться к ответу («отдых») по своему усмотрению.

Будьте осторожны, чтобы использовать javascript для выполнения запросов REST API. Это связано с тем, что javascript является интерфейсным языком программирования, это означает, что код запускается на рабочем столе пользователя (ноутбук, телефон) и этот код может быть перехвачен хакерами и любым другим злоумышленником. Запросы REST API в javascript рекомендуются только в том случае, если вам не нужно передавать конфиденциальные данные, такие как ключи, пароль или личную информацию. В приведенном выше примере мы вызвали URL-адрес, чтобы перечислить все центры обработки данных (DC) в Rackcorp, которые не требуют аутентификации, они открыты для всего мира.

PHP:

In PHP usually developers use CURL function to connect through HTTP. In the sample bellow you can understand how to implement a REST API request from your server to another server.

<?php

$v = 'v2.7';
$url = "https://api.rackcorp.net/api/". $v . "/dcs";
$query = [];

$curl = curl_init($url);
curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($query));
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($curl);

if($response) {
	return json_decode($response, true);
}

return false;

As you can see we created the same variables 'v' and 'query' in PHP to call the REST API url. Them, we start creating the CURL initial command. We set some options in the CURL function such as POSTFIELDS and RETURNTRANSFER. You have many other options that you can add to CURL PHP. Have a look in the PHP docs to find out  the best approach for your code logic. 

Conclusion:

REST API request is a quite simple way to get, insert, and update data through internet with small effort. Nowadays, Mostly of services through the internet has implemented REST API functions and RACKCORP also has its own standard. If you need to connect to us using REST API, read more in  RACKCORP REST API