در این مقاله، ما میخواهیم در مورد یکی از مهمترین مفاهیم در ساخت RESTful API ها صحبت کنیم – HATEOAS و یاد بگیریم که چطور HATEOAS را در ASP.NET Core Web API پیاده سازی کنیم. این مقاله، به مفاهیمی که تا به الان در صفحه بندی، فیلترینگ، جست و جو، مرتب سازی و بخصوص data-shaping پیاده سازی کرده ایم، وابسته بوده و بر پایه و اساسی که در این مقالات قرار داده ایم بنا می شود.
این مقاله شامل یک سری مفاهیم پیشرفته در مورد REST و Web API است. اگر فکر میکنید که در این زمینه سردرگم هستید و یا اینکه قسمتی از کل داستان را فراموش کرده اید، یک قدم به عقب برگردید و اول از همه، زمان خود را بر روی مرور این مقالات بگذارید. همچنین اگر میخواهید که مقالات مربوطه را بیشتر رصد نمایید، ما در سرتاسر مقاله، شما را به آنها لینک میدهیم.
اگر میخواهید ما را در این مقاله همراهی کنید، میتوانید از نقطه شروع پروژه استفاده کنید و اگر میخواهید solution نهایی را بگیرید یا اگر جایی در پروژه برایتان نامفهوم است میتوانید پروژه تکمیل شده این مقاله را ببینید.
توجه: برای دنبال کردن این مقاله، کمی دانش پیشنیاز لازم است. اگر نحوه ایجاد دیتابیس یا نحوه کارکرد معماری مورد نظر را نمیدانید، به شدت توصیه میکنم که مقاله های مورد نظر را رصد نمایید.
در این مقاله، ما میخواهیم یاد بگیریم که:
- HATEOAS چیست و چرا انقدر مهم است؟
- توسعه Model در آماده سازی برای پیاده سازی HATEOAS
- پیاده سازی HATEOAS در ASP.NET Core Web API
- تست Solution
- بهبود Solution
- معرفی Media Type های سفارشی
- نتیجه گیری
حالا بریم تا ببینیم این HATEOAS چیست.
HATEOAS چیست و چرا انقدر مهم است؟
HATEOAS (Hypermedia as the Engine of Application State) یک معیار بسیار مهم برای REST است. بدون آن ، REST API را نمی توان RESTful دانست و بسیاری از مزایایی که با پیاده سازی یک معماری REST به دست می آوریم در دسترس نخواهند بود.
Hypermedia به هر نوع از محتوایی که شامل پیوندها به انواع رسانه ها مانند سندها، تصاویر، ویدئوها و … باشد گفته میشود.
معماری REST به ما این امکان را می دهد که پیوندهای Hypermedia را در response های خود به صورت پویا ایجاد کنیم و بنابراین navigation را برای ما بسیار آسان تر میسازد.
برای درک بهتر این موضوع، به وب سایتی فکر کنید که با استفاده از لینک های پیوندی به شما کمک می کند تا به قسمت های مختلف آن بروید. شما همچین ویژگی را میتوانید با HATEOAS در REST API تان بدست آورید.
وب سایتی را تصور کنید که دارای یک صفحه اصلی است و شما در آن قرار دارید، اما هیچ پیوندی در هیچ جای آن وجود ندارد. شما باید وب سایت را بالا و پایین کنید یا روش دیگری را برای پیمایش در آن پیدا کنید تا به محتوای مورد نظر خودتان برسید. ما نمیگوییم که وبسایت مانند یک REST API است، اما اصل موضوع همین است.
قدرت توانایی کاوش کردن API به تنهایی می تواند بسیار مفید باشد.
حال ببینیم چطور آن واقعا کار میکند.
نمونه Response با HATEOAS پیاده سازی شده
بیاید بگوییم که میخواهیم تعدادی Owner را از API مان بگیریم.
اما چطور باید این کار را انجام دهیم؟
ما حتی endpoint مربوط به owner ها را نمیدانیم. خب، اول به سراغ چیزی که نحوه request آن را میدانیم میرویم و آن root برنامه میباشد:
|
1 |
https://localhost:50001/api |
root endpoint ما، باید جزییات لازم را در مورد API ما یا بهتر بگویم اینکه از چه جایی باید شروع به کاوش کنیم را به ما بگوید:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
[ { "href": "http://localhost:5001/api", "rel": "self", "method": "GET" }, { "href": "http://localhost:5001/api/owner", "rel": "owner", "method": "GET" }, { "href": "http://localhost:5000/api/owner", "rel": "create_owner", "method": "POST" } ] |
خوب ، اکنون ما می دانیم که بلافاصله چه چیزی در دسترس ما است و می توانیم برای به دست آوردن owner های موجود اقدام کنیم:
|
1 |
http://localhost:5001/api/owner |
و در واقع ما owner ها را دریافت میکنیم:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 |
[ { "Id": "24fd81f8-d58a-4bcc-9f35-dc6cd5641906", "Name": "John Keen", "DateOfBirth": "1980-12-05T00:00:00", "Address": "61 Wellfield Road", "Links": [ { "href": "https://localhost:5001/api/owner/24fd81f8-d58a-4bcc-9f35-dc6cd5641906", "rel": "self", "method": "GET" }, { "href": "https://localhost:5001/api/owner/24fd81f8-d58a-4bcc-9f35-dc6cd5641906", "rel": "delete_owner", "method": "DELETE" }, { "href": "https://localhost:5001/api/owner/24fd81f8-d58a-4bcc-9f35-dc6cd5641906", "rel": "update_owner", "method": "PUT" } ] }, { "Id": "261e1685-cf26-494c-b17c-3546e65f5620", "Name": "Anna Bosh", "DateOfBirth": "1974-11-14T00:00:00", "Address": "27 Colored Row", "Links": [ { "href": "https://localhost:5001/api/owner/261e1685-cf26-494c-b17c-3546e65f5620", "rel": "self", "method": "GET" }, { "href": "https://localhost:5001/api/owner/261e1685-cf26-494c-b17c-3546e65f5620", "rel": "delete_owner", "method": "DELETE" }, { "href": "https://localhost:5001/api/owner/261e1685-cf26-494c-b17c-3546e65f5620", "rel": "update_owner", "method": "PUT" } ] }, "..." ] |
همانطور که میبینید، ما لیستی از owner ها و تمام اکشنهایی که میتوانیم بر روی هریک از آنها انجام دهیم و غیره را اینجا دریافت کردیم.
بنابراین، این یک روش خوب برای ساختن یک API خود کاشف و تکامل یافته است.
یک Link چیست؟
بر طبق RFC5988، یک link، “یک اتصال بین دو منبع است که توسط Internationalised Resource Identifiers (IRIs) شناسایی می شود”. به زبان ساده ما از لینکها برای پیمایش اینترنت یا بهتر بگوییم برای پیمایش منابع موجود در اینترنت استفاده می کنیم.
response های ما شامل آرایه ای از لینکها است که این لینکها شامل تعدادی خصوصیت بر طبق RFC است.
- href – بیانگر یک target URI است.
- rel – بیانگر نوع رابطه لینک مورد نظر است، به این معنی که نحوه رابطه context کنونی را با target resource مورد نظر توصیف میکند.
- method – ما یک متد HTTP نیاز داریم تا بدانیم که چگونه target URI های یکسان را از هم تشخیص دهیم.
معایب/مزایای پیاده سازی HATEOAS
بنابراین تمام مزایایی که میتوانیم از پیاده سازی HATEOAS بدست آوریم چه چیزهایی هستند؟
پیاده سازی HATEOAS ساده نیست ، اما منفعتهایی که از پیاده سازی آن عاید ما میشود ارزش آن را دارد.. تعدادی از مواردی که از پیاده سازی HATEOAS میتوانیم انتظار داشته باشیم بدست آوریم عبارتند از:
- API مورد نظر تبدیل به یک API خودکاشف و قابل کاوش میشود.
- یک client میتواند از لینکها برای پیاده سازی logic خود استفاده کند. این باعث میشود کار راحت تر شود و هر تغییری که در ساختار API اتفاق میفتد به طور مستقیم به داخل client منعکس میشود.
- سرور، کنترل state برنامه و ساختار URL را در دست میگیرد و نه برعکس.
- از relation های لینک، می توان برای نشان دادن مستندات توسعه دهنده استفاده کرد.
- ورژن بندی از طریق hyperlink ها، آسانتر میشود.
- فراخوانیهای تراکنش وضعیت نامعتبر کاهش میابد.
- API بدون تفکیک client ها، تکامل یافته میشود.
ما میتوانیم خیلی کارها با HATEOAS انجام دهیم. اما پیاده سازی تمام این feature ها، راحت نیست. ما باید اسکوپ API خود را به خاطر بسپاریم و اگر واقعاً به همه اینها احتیاج داریم، تفاوت زیادی بین یک API عمومی با حجم درخواست بالا و برخی از API های داخلی که برای برقراری ارتباط بین قسمت های همان سیستم مورد نیاز است وجود دارد.
مانند هرچیز دیگری، context همه چیز است. آن را ساده نگه دارید.
در حال حاضر این تئوری، بیش از حد کافی است. اجازه دهید تا وارد عمل شویم و ببینیم تا پیاده سازی واقعی HATEOAS چطور به نظر میرسد.
توسعه Model در آماده سازی برای پیاده سازی HATEOAS
با concept ای که تا الان یاد گرفتیم کارمان را شروع میکنیم و آن Link است. اول از همه، ما موجودیت Link را در پوشه Models پروژه Entities ایجاد میکنیم:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
public class Link { public string Href { get; set; } public string Rel { get; set; } public string Method { get; set; } public Link() { } public Link(string href, string rel, string method) { Href = href; Rel = rel; Method = method; } } |
توجه داشته باشید که ما اینجا یک سازنده خالی هم داریم. ما برای اهداف XML serialization به آن نیاز خواهیم داشت ، بنابراین آن را اینجا داشته باشید.
در مرحله بعد، ما باید یک کلاس ایجاد کنیم که شامل تمام link های ما خواهد بود – LinkResourceBase:
|
1 2 3 4 5 6 7 8 9 |
public class LinkResourceBase { public LinkResourceBase() { } public List<Link> Links { get; set; } = new List<Link>(); } |
و در آخر، چون response ما باید root کنترلر را توصیف کند، به یک wrapper برای link هایمان نیاز داریم:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
public class LinkCollectionWrapper<T> : LinkResourceBase { public List<T> Value { get; set; } = new List<T>(); public LinkCollectionWrapper() { } public LinkCollectionWrapper(List<T> value) { Value = value; } } |
این کلاس ممکن است در حال حاضر زیاد منطقی نباشد ، اما با ما همراه باشید و بعداً در این مسیر برایتان شفاف خواهد شد. در حال حاضر، فرض میکنیم ما link های خود را در کلاس دیگری برای اهداف ارائه response قرار داده ایم.
از آنجا که response ما حاوی link ها نیز خواهد بود ، باید قوانین XML serialization را گسترش دهیم، طوریکه XML response ما، link های قالب بندی شده صحیح را برگردانند. بدون آن، ما چیزی مانند این را دریافت خواهیم کرد:
|
1 |
<Links>System.Collections.Generic.List`1[Entites.Models.Link]<Links> |
بنابرایم ما باید متد WriteXmlElement برای پشتیبانی از link ها توسعه دهیم:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 |
public void WriteXml(XmlWriter writer) { foreach (var key in expando.Keys) { var value = expando[key]; WriteLinksToXml(key, value, writer); } } private void WriteLinksToXml(string key, object value, XmlWriter writer) { writer.WriteStartElement(key); if (value.GetType() == typeof(List<Link>)) { foreach (var val in value as List<Link>) { writer.WriteStartElement(nameof(Link)); WriteLinksToXml(nameof(val.Href), val.Href, writer); WriteLinksToXml(nameof(val.Method), val.Method, writer); WriteLinksToXml(nameof(val.Rel), val.Rel, writer); writer.WriteEndElement(); } } else { writer.WriteString(value.ToString()); } writer.WriteEndElement(); } |
همانند کاری که در مقاله data shaping انجام داده بودیم، ما اینجا زیاد وارد جزییات نمیشویم، چرا که این خارج از محدوده مقاله میباشد، اما logic آن نیز زیاد پیچیده نیست. به طور خلاصه، ما بررسی کردیم که آیا type از نوع List<Link> است یا خیر. که اگر اینطور است سپس بر روی کل link ها حلقه میزنیم و متد را به صورت بازگشتی برای هریک از خصوصیات: href, method, و rel فراخوانی میکنیم.
این تمام چیزی است که در حال حاضر نیاز داریم. ما اکنون یک پایه محکم برای پیاده سازی HATEOAS در کنترلمان داریم.
پیاده سازی HATEOAS در ASP.NET Core Web API
حالا سراغ OwnerController میرویم و در واقع HATEOAS را پیاده سازی میکنیم.
اول از همه، باید کنترلرمان را با کلاس LinkGenerator توسعه دهیم که به ما کمک میکند تا link هایی که میخواهیم را بسازیم:
|
1 2 3 4 5 6 7 8 9 10 11 12 |
private ILoggerManager _logger; private IRepositoryWrapper _repository; private LinkGenerator _linkGenerator; public OwnerController(ILoggerManager logger, IRepositoryWrapper repository, LinkGenerator linkGenerator) { _logger = logger; _repository = repository; _linkGenerator = linkGenerator; } |
سپس باید متد GetOwners مان را برای افزودن link های مرتبط با owner های دریافت شده از دیتابیس توسعه دهیم:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 |
[HttpGet] public IActionResult GetOwners([FromQuery] OwnerParameters ownerParameters) { if (!ownerParameters.ValidYearRange) { return BadRequest("Max year of birth cannot be less than min year of birth"); } var owners = _repository.Owner.GetOwners(ownerParameters); var metadata = new { owners.TotalCount, owners.PageSize, owners.CurrentPage, owners.TotalPages, owners.HasNext, owners.HasPrevious }; Response.Headers.Add("X-Pagination", JsonConvert.SerializeObject(metadata)); _logger.LogInfo($"Returned {owners.TotalCount} owners from database."); for (var index = 0; index < owners.Count(); index++) { var ownerLinks = CreateLinksForOwner(owners[index].Id, ownerParameters.Fields); owners[index].Add("Links", ownerLinks); } var ownersWrapper = new LinkCollectionWrapper<Entity>(owners); return Ok(CreateLinksForOwners(ownersWrapper)); } |
ما اینجا، یک حلقه بر روی تمام owner هایی که از دیتابیس دریافت شده زده ایم و لینکهای مربوطه را به آنها اضافه کرده ایم. بعد از آن، ما owners collection را wrap میکنیم و link هایی که برای کل collection مهم هستند را ایجاد میکنیم.
حالا فقط باید متدهای CreateLinksForOwner و CreateLinksForOwners را پیاده سازی کنیم:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 |
private IEnumerable<Link> CreateLinksForOwner(Guid id, string fields = "") { var links = new List<Link> { new Link(_linkGenerator.GetUriByAction(HttpContext, nameof(GetOwnerById), values: new { id, fields }), "self", "GET"), new Link(_linkGenerator.GetUriByAction(HttpContext, nameof(DeleteOwner), values: new { id }), "delete_owner", "DELETE"), new Link(_linkGenerator.GetUriByAction(HttpContext, nameof(UpdateOwner), values: new { id }), "update_owner", "PUT") }; return links; } private LinkCollectionWrapper<Entity> CreateLinksForOwners(LinkCollectionWrapper<Entity> ownersWrapper) { ownersWrapper.Links.Add(new Link(_linkGenerator.GetUriByAction(HttpContext, nameof(GetOwners), values: new { }), "self", "GET")); return ownersWrapper; } |
ذکر چند نکته اینجا حائز اهمیت است.
ما باید هنگام ایجاد link ها، fields را در نظر بگیریم زیرا ممکن است از آنها در request های خود استفاده کنیم. ما link ها را با استفاده از متد LinkGenerator.GetUriByAction ایجاد میکنیم که HttpContext، نام action و values که باید برای ایجاد URL معتبر مورد استفاده قرار بگیرد را به عنوان ورودی میگیرد. در مورد OwnersController، ما owner id و fields را به عنوان آرگومان ارسال میکنیم.
response که ما اینجا انتظار داریم دقیقا همان response است که ما به عنوان مثال استفاده کرده بودیم.
ما کاری مشابه برای متد GetOwnerById مان انجام میدهیم:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
[HttpGet("{id}", Name = "OwnerById")] public IActionResult GetOwnerById(Guid id, [FromQuery] string fields) { var owner = _repository.Owner.GetOwnerById(id, fields); if (owner.Id == Guid.Empty) { _logger.LogError($"Owner with id: {id}, hasn't been found in db."); return NotFound(); } owner.Add("Links", CreateLinksForOwner(owner.Id, fields)); return Ok(owner); } |
همانطور که میبینید logic اینجا برای یک owner خیلی راحت تر است، زیرا نیازی به wrap کردن آن نداریم.
ما می خواهیم همین کار را برای AccountController انجام دهیم، اما با کمی تفاوت. همانطور که میدانید endpoint مربوط به AccountController کمی متفاوت است:
|
1 2 |
/api/owner/{ownerId}/account /api/owner/{ownerId}/account/{accountId} |
باید زمانیکه لینکهای HATEOAS را میسازیم، این را در نظر بگیریم:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
private List<Link> CreateLinksForAccount(Guid ownerId, Guid id, string fields = "") { var links = new List<Link> { new Link(_linkGenerator.GetUriByAction(HttpContext, nameof(GetAccountForOwner), values: new { ownerId, id, fields }), "self", "GET"), }; return links; } private LinkCollectionWrapper<Entity> CreateLinksForAccounts(LinkCollectionWrapper<Entity> accountsWrapper) { accountsWrapper.Links.Add(new Link(_linkGenerator.GetUriByAction(HttpContext, nameof(GetAccountsForOwner), values: new { }), "self", "GET")); return accountsWrapper; } |
پیاده سازی AccountController ما، شامل متدهای Create, Update یا Delete نیست، بنابراین پیاده سازی آن راحت تر است. اما همانطور که میتوانید ببینید، علاوه بر account id، باید owner id را نیز اینجا در نظر بگیریم. به منظور تولید صحیح link ها، ما باید fields را نیز در این حالت در نظر بگیریم.
خب، خیلی سریع این logic که پیاده سازی کردیم را تست کنیم و ببینیم چطور کار میکند.
تست Solution
با یک query ساده به owners endpoint شروع میکنیم:
|
1 |
GET https://localhost:5001/api/owner |
این باید لیستی از owner ها را به همراه link های اضافه شده به آنها برگرداند:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 |
{ "value": [ { "Id": "24fd81f8-d58a-4bcc-9f35-dc6cd5641906", "Name": "John Keen", "DateOfBirth": "1980-12-05T00:00:00", "Address": "61 Wellfield Road", "Links": [ { "href": "https://localhost:5001/api/owner/24fd81f8-d58a-4bcc-9f35-dc6cd5641906", "rel": "self", "method": "GET" }, { "href": "https://localhost:5001/api/owner/24fd81f8-d58a-4bcc-9f35-dc6cd5641906", "rel": "delete_owner", "method": "DELETE" }, { "href": "https://localhost:5001/api/owner/24fd81f8-d58a-4bcc-9f35-dc6cd5641906", "rel": "update_owner", "method": "PUT" } ] }, ... ... ... "links": [ { "href": "https://localhost:5001/api/owner", "rel": "self", "method": "GET" } ] } |
همانطور که میبینید، تمام link هایی که برای owner مان تعریف کرده بودیم اینجا وجود دارد. کل کالکشن owner ها، در موجودیت “wrap ،“value شده است، زیرا درست در انتها، ما یک links که “self” یا بهتر بگوییم نحوه رسیدن به کنترلر را توصیف میکند را تعریف میکنیم. ما میتوانیم آن را هرزمان که بخواهیم با دیگر link های مرتبط که برای کنترلر مهم هستند را توسعه دهیم.
این بود کل ماجرای wrapper که پیاده سازی کردیم.
حال تستمان را با یک owner انجام میدهیم:
|
1 |
GET https://localhost:5001/api/owner/24fd81f8-d58a-4bcc-9f35-dc6cd5641906 |
نتیجه باید به صورت زیر باشد:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
{ "Id": "24fd81f8-d58a-4bcc-9f35-dc6cd5641906", "Name": "John Keen", "DateOfBirth": "1980-12-05T00:00:00", "Address": "61 Wellfield Road", "Links": [ { "href": "https://localhost:5001/api/owner/24fd81f8-d58a-4bcc-9f35-dc6cd5641906", "rel": "self", "method": "GET" }, { "href": "https://localhost:5001/api/owner/24fd81f8-d58a-4bcc-9f35-dc6cd5641906", "rel": "delete_owner", "method": "DELETE" }, { "href": "https://localhost:5001/api/owner/24fd81f8-d58a-4bcc-9f35-dc6cd5641906", "rel": "update_owner", "method": "PUT" } ] } |
فقط یک owner، بدون هیچگونه wrapper.
حالا سعی میکنیم تا account های مربوط به همین owner را بگیریم:
|
1 |
GET https://localhost:5001/api/owner/24fd81f8-d58a-4bcc-9f35-dc6cd5641906/account |
ما لیستی از account های این owner و link های مربوط به آنها را دریافت میکنیم:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 |
{ "value": [ { "Id": "371b93f2-f8c5-4a32-894a-fc672741aa5b", "DateCreated": "1999-05-04T00:00:00", "AccountType": "Domestic", "OwnerId": "24fd81f8-d58a-4bcc-9f35-dc6cd5641906", "Links": [ { "href": "https://localhost:5001/api/owner/24fd81f8-d58a-4bcc-9f35-dc6cd5641906/account/371b93f2-f8c5-4a32-894a-fc672741aa5b", "rel": "self", "method": "GET" } ] } ... ], "links": [ { "href": "https://localhost:5001/api/owner/24fd81f8-d58a-4bcc-9f35-dc6cd5641906/account", "rel": "self", "method": "GET" } ] } |
و در آخر، یک تک account را تست میکنیم:
|
1 |
GET https://localhost:5001/api/owner/24fd81f8-d58a-4bcc-9f35-dc6cd5641906/account/371b93f2-f8c5-4a32-894a-fc672741aa5b |
نتیجه باید در این مرحله کاملاً واضح باشد:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
{ "Id": "371b93f2-f8c5-4a32-894a-fc672741aa5b", "DateCreated": "1999-05-04T00:00:00", "AccountType": "Domestic", "OwnerId": "24fd81f8-d58a-4bcc-9f35-dc6cd5641906", "Links": [ { "href": "https://localhost:5001/api/owner/371b93f2-f8c5-4a32-894a-fc672741aa5b/account/371b93f2-f8c5-4a32-894a-fc672741aa5b", "rel": "self", "method": "GET" } ] } |
یک link، نحوه گرفتن آن account را توصیف می کند. همانطور که مشاهده می کنید، دو id در این link وجود دارد ، بنابراین کار بزرگی را در این پیاده سازی انجام داده ایم.
حالا تنها چیزی که برای تست کردن باقی میماند این است که چطور آن کار میکند زمانیکه فیلدهایی که نیاز داریم را انتخاب میکنیم:
|
1 |
GET https://localhost:5001/api/owner?fields=name |
و با کمال تعجب، این کار نمی کند.
چرا؟
بهبود Solution
خب، همانطور که مشاهده کردید، پیاده سازی HATEOAS، به داشتن id های موجود برای ساخت link ها برای response متکی است. از طرفی دیگر، Data shaping، این امکان را به ما میدهد که فقط field هایی که نیاز داریم را برگردانیم و در سناریوی تستمان، ما فقط نام owner ها را میخواستیم. این بدان معناست که ما id این owner ها را برنمیگرداندیم و ما در حال حاضر نمیتوانیم URI های target را بسازیم.
برای حل این مشکل، ما میخواهیم مطمئن شویم که id همیشه به کنترلر برگردانده میشود.
اول از همه، ما یک wrapper به نام ShapedEntity که علاوه بر entity، شامل ویژگی id نیز است پیاده سازی میکنیم:
|
1 2 3 4 5 6 7 8 9 10 |
public class ShapedEntity { public ShapedEntity() { Entity = new Entity(); } public Guid Id { get; set; } public Entity Entity { get; set; } } |
سپس، تمام جاهایی که از کلاس Entity در کل پروژه استفاده کرده ایم را با ShapedEntity جایگزین میکنیم. در کلاسهایی که شما باید کلاسهای Entity استفاده شده در آن را جایگزین کنید عبارتند از: AccountRepository, IAccountRepository, OwnerRepository, IOwnerRepository, DataShaper, و IDataShaper.
علاوه بر این، باید متد FetchDataForEntity در کلاس DataShaper را برای گرفتن id به طور جداگانه، توسعه دهیم:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
private ShapedEntity FetchDataForEntity(T entity, IEnumerable<PropertyInfo> requiredProperties) { var shapedObject = new ShapedEntity(); foreach (var property in requiredProperties) { var objectPropertyValue = property.GetValue(entity); shapedObject.Entity.TryAdd(property.Name, objectPropertyValue); } var objectProperty = entity.GetType().GetProperty("Id"); shapedObject.Id = (Guid)objectProperty.GetValue(entity); return shapedObject; } |
در حال حاضر، مهم نیست چه خصوصیاتی را با استفاده از data shaping دریافت میکنیم، بلکه تمام چیزهایی که باید با آن link ها را بسازیم را در اختیار داریم.
تنها کاری که باقی مانده است این است که اکشنهای کنترلرمان را کمی تغییر دهیم:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 |
[HttpGet] public IActionResult GetOwners([FromQuery] OwnerParameters ownerParameters) { ...//implementation var shapedOwners = owners.Select(o => o.Entity).ToList(); for (var index = 0; index < owners.Count(); index++) { var ownerLinks = CreateLinksForOwner(owners[index].Id, ownerParameters.Fields); shapedOwners[index].Add("Links", ownerLinks); } var ownersWrapper = new LinkCollectionWrapper<Entity>(shapedOwners); return Ok(CreateLinksForOwners(ownersWrapper)); } [HttpGet("{id}", Name = "OwnerById")] public IActionResult GetOwnerById(Guid id, [FromQuery] string fields) { var owner = _repository.Owner.GetOwnerById(id, fields); if (owner.Id == Guid.Empty) { _logger.LogError($"Owner with id: {id}, hasn't been found in db."); return NotFound(); } owner.Entity.Add("Links", CreateLinksForOwner(owner.Id, fields)); return Ok(owner.Entity); } |
کلاس AccountController نیز همین تغییرات را شامل میشود.
حالا این query را مجددا امتحان میکنیم:
|
1 |
GET https://localhost:5001/api/owner?fields=name |
و در پاسخ، این را دریافت میکنیم:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 |
{ "value": [ { "Name": "John Keen", "Links": [ { "href": "https://localhost:5001/api/owner/24fd81f8-d58a-4bcc-9f35-dc6cd5641906?fields=name", "rel": "self", "method": "GET" }, { "href": "https://localhost:5001/api/owner/24fd81f8-d58a-4bcc-9f35-dc6cd5641906", "rel": "delete_owner", "method": "DELETE" }, { "href": "https://localhost:5001/api/owner/24fd81f8-d58a-4bcc-9f35-dc6cd5641906", "rel": "update_owner", "method": "PUT" } ] }, ... ], "links": [ { "href": "https://localhost:5001/api/owner", "rel": "self", "method": "GET" } ] } |
عالی! این دقیقا همان چیزی است که ما میخواستیم.
معرفی Media Type های سفارشی
اکنون، برگرداندن link های HATEOAS، یک امکان اضافی خوب برای API ما به حساب می آید. اما همانطور که می بینید response ها می توانند اینجا کمی طولانی باشند و ما به عمد تعدادی از آنها را کوتاه کردیم تا مقاله قابلیت خوانایی بیشتری داشته باشد.
ما می خواهیم به یک کاربر API توانایی تعیین نوع response را نیز بدهیم.
و چطور میتوانیم این کار را انجام دهیم؟
پاسخ به این سوال، بهره گیری از قدرت media type های سفارشی است.
ما می خواهیم media type های خودمان را ایجاد کنیم تا زمانیکه می خواهیم یک response را که شامل link های HATEOAS است برگردانیم را از آنها استفاده کنیم. اما میخواهیم زمانیکه از آن استفاده نکردیم، response هیچ link را شامل نشود و response خیلی ساده برگدانده شود مانند آنچه که قبلا آن را return میکردیم.
قبل از اینکه شروع کنیم، ببینیم چطور میتوانیم یک media type سفارشی ایجاد کنیم. یک media type سفارشی، باید چیزی به مانند این به نظر برسد:
application/vnd.expertmarket.hateoas+json. برای مقایسه آن با json media type معمولی که به طور پیش فرض از آن استفاده می کنیم:
application/json.
بنابراین اجازه دهید قسمت های مختلف یک media type سفارشی را تجزیه و تحلیل کنیم:
vnd– پیشوند vendor که همیشه وجود دارد.- expertmarket – شناسه vendor که ما اینجا expertmarket را انتخاب کرده ایم، چرا که نه.
- hateoas – نام media type
json– پسوندی که می توانیم از آن به عنوان توصیف استفاده کنیم که مثلاً می خواهیم پاسخ json باشد یا XML.
حالا آن را در اپلیکیشنمان پیاده سازی میکنیم.
ثبت Media Type های سفارشی
اول از همه، ما میخواهیم media type های سفارشی را در middleware ثبت کنیم، در غیر اینصورت، خطای 406 Not Acceptable میگیریم.
اجازه دهید یک متد extension جدید به ServiceExtensions مان اضافه کنیم:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
public static void AddCustomMediaTypes(this IServiceCollection services) { services.Configure<MvcOptions>(config => { var newtonsoftJsonOutputFormatter = config.OutputFormatters .OfType<NewtonsoftJsonOutputFormatter>()?.FirstOrDefault(); if (newtonsoftJsonOutputFormatter != null) { newtonsoftJsonOutputFormatter.SupportedMediaTypes.Add("application/vnd.expertmarket.hateoas+json"); } var xmlOutputFormatter = config.OutputFormatters .OfType<XmlDataContractSerializerOutputFormatter>()?.FirstOrDefault(); if (xmlOutputFormatter != null) { xmlOutputFormatter.SupportedMediaTypes.Add("application/vnd.expertmarket.hateoas+xml"); } }); } |
ما اینجا دو media type سفارشی ثبت کردیم:application/vnd.expertmarket.hateoas+json برای newtonSoftJsonSerializerOutputFormatter و application/vnd.expertmarket.hateoas+xml برای xmlDataContractSerializerOutputFormatter. این باعث میشود که دیگر یک 406 Not Acceptable response دریافت نکنیم.
آن را به Startup.cs در متد ConfigureServices بعد از متد AddControllers اضافه کنید:
|
1 2 3 4 5 6 7 8 |
services.AddControllers(config => { config.RespectBrowserAcceptHeader = true; config.ReturnHttpNotAcceptable = true; }).AddXmlDataContractSerializerFormatters() .AddNewtonsoftJson(); services.AddCustomMediaTypes(); |
این متد، مسئولیت ثبت media type های سفارشی را بر عهده دارد.
پیاده سازی یک Media Type Validation Filter
اکنون، از آنجا که media type های سفارشی را پیاده سازی کرده ایم، میخواهیم Accept header مان در request هایمان وجود داشته باشد تا بتوانیم response پربار HATEOAS را تشخیص دهیم زمانیکه کاربر آن را درخواست کرد.
برای این منظور، ما یک ActionFilter پیاده سازی میکنیم که Accept header و media type های ما را validate خواهد کرد:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 |
public class ValidateMediaTypeAttribute : IActionFilter { public void OnActionExecuting(ActionExecutingContext context) { var acceptHeaderPresent = context.HttpContext.Request.Headers.ContainsKey("Accept"); if (!acceptHeaderPresent) { context.Result = new BadRequestObjectResult($"Accept header is missing."); return; } var mediaType = context.HttpContext.Request.Headers["Accept"].FirstOrDefault(); if (!MediaTypeHeaderValue.TryParse(mediaType, out MediaTypeHeaderValue outMediaType)) { context.Result = new BadRequestObjectResult($"Media type not present. Please add Accept header with the required media type."); return; } context.HttpContext.Items.Add("AcceptHeaderMediaType", outMediaType); } public void OnActionExecuted(ActionExecutedContext context) { } } |
ما اینجا اول موجودیت Accept header را بررسی میکنیم. اگر موجود نبود، یک BadRequest برمیگردانیم. اما اگر وجود داشت، media type را parse میکنیم و اگر media type معتبر وجود نداشته باشد نیز یک BadRequest برمیگردانیم.
زمانیکه تستهای validation را با موفقیت پشت سرگذاشتیم، سپس parse media type شده را به HttpContext کنترلر اضافه میکنیم.
فراموش نکنید که این filter را در IoC ثبت کنید:
|
1 |
services.AddScoped<ValidateMediaTypeAttribute>(); |
حالا باید اکشنهای GetOwners و GetOwnerById را با [ServiceFilter(typeof(ValidateMediaTypeAttribute))] برای این validation ها مزین کنیم.
در مورد logic این اکشنها نیز باید آنها را کمی توسعه دهیم:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 |
[HttpGet] [ServiceFilter(typeof(ValidateMediaTypeAttribute))] public IActionResult GetOwners([FromQuery] OwnerParameters ownerParameters) { //Implementation var shapedOwners = owners.Select(o => o.Entity).ToList(); var mediaType = (MediaTypeHeaderValue)HttpContext.Items["AcceptHeaderMediaType"]; if (!mediaType.SubTypeWithoutSuffix.EndsWith("hateoas", StringComparison.InvariantCultureIgnoreCase)) { return Ok(shapedOwners); } for (var index = 0; index < owners.Count(); index++) { var ownerLinks = CreateLinksForOwner(owners[index].Id, ownerParameters.Fields); shapedOwners[index].Add("Links", ownerLinks); } var ownersWrapper = new LinkCollectionWrapper<Entity>(shapedOwners); return Ok(CreateLinksForOwners(ownersWrapper)); } |
ما media type که در parse ،ValidateMediaTypeAttribute ActionFilter کردیم را اینجا خواندیم و آن را به نوع MediaTypeHeaderValue تبدیل کردیم. با استفاده از SubTypeWithoutSuffix.EndsWith در کلاس MediaTypeHeaderValue بررسی کرده ایم که آیا HATEOAS مورد درخواست قرار گرفته است یا خیر. اگر اینطور نبود، بلافاصله owner ها را برمیگردانیم. اما اگر اینطور بود، link ها را اضافه میکنیم و آنها را همانند قبل return میکنیم.
همین داستان برای اکشن GetOwnerById نیز صدق میکند:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
[HttpGet("{id}", Name = "OwnerById")] [ServiceFilter(typeof(ValidateMediaTypeAttribute))] public IActionResult GetOwnerById(Guid id, [FromQuery] string fields) { var owner = _repository.Owner.GetOwnerById(id, fields); if (owner.Id == Guid.Empty) { _logger.LogError($"Owner with id: {id}, hasn't been found in db."); return NotFound(); } var mediaType = (MediaTypeHeaderValue)HttpContext.Items["AcceptHeaderMediaType"]; if (!mediaType.SubTypeWithoutSuffix.EndsWith("hateoas", StringComparison.InvariantCultureIgnoreCase)) { _logger.LogInfo($"Returned shaped owner with id: {id}"); return Ok(owner.Entity); } owner.Entity.Add("Links", CreateLinksForOwner(owner.Id, fields)); return Ok(owner.Entity); } |
حالا ما اینها را در خروجی تست میکنیم. یک request ساده برای گرفتن owner ها را امتحان میکنیم و Accept request header آن را به application/json ست میکنیم:
|
1 |
GET https://localhost:5001/api/owner |
در پاسخ، باید این response را دریافت کنیم:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
[ { "Id": "24fd81f8-d58a-4bcc-9f35-dc6cd5641906", "Name": "John Keen", "DateOfBirth": "1980-12-05T00:00:00", "Address": "61 Wellfield Road" }, { "Id": "261e1685-cf26-494c-b17c-3546e65f5620", "Name": "Anna Bosh", "DateOfBirth": "1974-11-14T00:00:00", "Address": "27 Colored Row" }, ... ] |
و حالا در همین request، میتوانیم Accept header را به application/vnd.codemaze.hateoas+json تغییر دهیم و باید این response را دریافت کنیم:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 |
{ "value": [ { "Id": "24fd81f8-d58a-4bcc-9f35-dc6cd5641906", "Name": "John Keen", "DateOfBirth": "1980-12-05T00:00:00", "Address": "61 Wellfield Road", "Links": [ { "href": "https://localhost:5001/api/owner/24fd81f8-d58a-4bcc-9f35-dc6cd5641906", "rel": "self", "method": "GET" }, { "href": "https://localhost:5001/api/owner/24fd81f8-d58a-4bcc-9f35-dc6cd5641906", "rel": "delete_owner", "method": "DELETE" }, { "href": "https://localhost:5001/api/owner/24fd81f8-d58a-4bcc-9f35-dc6cd5641906", "rel": "update_owner", "method": "PUT" } ] }, ... ], "links": [ { "href": "https://localhost:5001/api/owner", "rel": "self", "method": "GET" } ] } |
خب، حالا همه چیز خارق العادست. اکنون ما ابزاری برای انتخاب بین response های از نوع json ، XML و HATEOAS را در اختیار داریم.
حال خلاصه میکنیم.
نتیجه گیری
HATEOAS در واقع یکی از مفیدترین و در عین حال یکی از پیچیده ترین مفاهیم REST برای پیاده سازی است. اینکه شما چگونه HATEOAS را در API خود پیاده سازی کنید و میزان سرمایه گذاری در صیقل دادن آن به خود شما بستگی دارد. HATEOAS به آسانی یک موردی است که یک API عالی را از نوع خوب یا بد جدا میکند.
حال مواردی که در این مقاله یاد گرفتیم این است که:
- HATEOAS چیست و به چه اندازه در دنیای RESTful اهمیت دارد
- نحوه پیاده سازی HATEOAS در پروژه ASP.NET Core WebAPI به چه صورت است
- نحوه بهبود solution جهت اینکه بتواند با data shaping خوب کار کند چگونه است
- نحوه پشتیبانی از XML serialization آبجکتهای داینامیک با link های HATEOAS به چه صورت است
- media type های سفارشی چیست و چطور با استفاده از آنها میتوانیم HATEOAS را به عنوان یک گزینه اختیاری در response هایمان بگنجانیم
این مقاله بسیار طولانی است، اما امیدواریم که چیز جدیدی را از آن یاد گرفته باشید و اگر مجددا درک آن برایتان سخت و دشوار است، پروژه نهایی ما را بررسی کنید و solution خودتان را با ما مقایسه و مورد سنجش قرار دهید.
