Hi,

Im Rahmen einer Webservices Vorlesung habe ich diverse Dokumentationen für REST APIs geschrieben und ich dachte ich teile das hier mit euch.

Was ist REST?
= Representational State Transfer

REST ist eine Abstraktion der Struktur und des Verhaltens des Word Wide Webs. Bei REST wird über die Zugriffsmethode des Protokolls sowie einer URI eine Repräsentation oder Modifikation einer Ressource angefragt.
REST setzt auf dem HTTP Protokoll auf, was sehr günstig ist da das Protokoll bereits REST konform arbeitet. REST Services sind zustandslos, d.h. der Server speichert keine Zwischenzustände zwischen zwei Anfragen. Das bringt den Vorteil das REST-APIs sehr hoch skalierbar sind, da die Last auf mehrere Rechner verteilt werden kann, da alle Informationen die vom Client benötigt werden in der Anfrage enthalten sind.

HTTP gestüztes REST bietet diese Methoden:


ACHTUNG: Richtige REST-APIs müssen das HATEOAS (Hypermedia As The Engine Of Application State) Prinzip implementieren. Das heißt das die Ressourcen, ähnlich wie im World Wide Web, untereinander verlinkt sein sollen.
Einfaches Beispiel einer Kunden-Verwaltung:
GET some/api/Customer/1 würde idealerweise eine solche Antwort zurückgeben:

Das hat zur Folge, dass man anhand des links auf alle Orders des Kunden sofort zugreifen kann ohne aus der OrderID und der API Dokumentation selbst eine URL zusammenbasteln muss.

Für die Verlinkung verwendet das folgende Beispiel den SIREN Formatter (die notwendigen Klassen hänge ich unten an). Siren kapselt alle Entitäten mit zugehörigen Eigenschaften in generische Objekte. Diese Objekte erhalten sogenannte Links zueinander. Außerdem hat jede Entität zusätzlich sogenannte Actions, d.h. eine Auflistung aller Operationen, die die API auf dem angefragten Objekt anbietet.

Erstellung einer REST-API

1. Erstellung der Basisklassen, die der Service anbieten soll. In unserem Fall die Customer-Klasse:
   

   C#-Quellcode

   1. public class Customer
   2. {
   3. public int Id { get; set; }
   4. public string Name { get; set; }
   5. public DateTime LastContact { get; set; }
   6. public bool IsFavorite { get; set; }
   7. }
   
   
2. Implementierung der Datenquelle, z.B. mit Hilfe des Repository-Patterns:
   

   C#-Quellcode

   1. public static class CustomerRepository
   2. {
   3. private static readonly Dictionary<int, Customer> s_Repository = new Dictionary<int, Customer>();
   5. static CustomerRepository()
   6. {
   7. var c1 = new Customer { Id = 1, Name = "Hugo", LastContact = new System.DateTime(2016, 3, 21, 12, 30, 23) };
   8. s_Repository.Add(c1.Id, c1);
   9. s_Repository.Add(2, new Customer { Id = 2, Name = "Gabi", LastContact = new System.DateTime(2016, 3, 22, 11, 40, 53) });
   10. s_Repository.Add(3, new Customer { Id = 3, Name = "Chelsea Manning", LastContact = new System.DateTime(2017, 10, 1, 12, 30, 23)});
   11. s_Repository.Add(4, new Customer { Id = 4, Name = "Lars Kaufmann" });
   12. }
   14. public static IEnumerable<Customer> GetAll()
   15. {
   16. return s_Repository.Values;
   17. }
   18. public static Customer Get(int id)
   19. {
   20. return s_Repository[id];
   21. }
   23. public static void Add(Customer customer)
   24. {
   25. s_Repository.Add(customer.Id, customer);
   26. }
   28. public static void Update(Customer customer)
   29. {
   30. s_Repository[customer.Id] = customer;
   31. }
   33. public static void Delete(int id)
   34. {
   35. s_Repository.Remove(id);
   36. }
   38. public static bool TryGetValue(int id, out Customer customer)
   39. {
   40. return s_Repository.TryGetValue(id, out customer);
   41. }
   42. }
   
   An dieser Stelle würde man hier eine Verbindung zu einer Datenbank aufbauen o.ä. aber um das ganze replizierbar zu machen verwendet das Beispiel statische Daten.
   
3. Siren und SirenFormatter importieren, an den beiden Klassen muss nichts geändert werden. In der StartUp.cs muss allerdings der SirenFormatter noch ausgewählt werden:
   

   C#-Quellcode

   1. // This method gets called by the runtime. Use this method to add services to the container.
   2. public void ConfigureServices(IServiceCollection services) {
   3. services.AddMvc( options=>options.OutputFormatters.Add(new Hypermedia.SirenFormatter()) );
   4. }
   
   
4. Erstellen des Controllers. Idealerweise hat jedes Objekt der Domäne einen eigenen Controller.
   GET api/Customer liefert eine Liste aller Kunden
   GET api/Customer/1 liefert den Kunden mit der ID 1
   POST api/Customer fügt einen neuen Kunden hinzu
   POST api/CustomerFavourites makiert einen Kunden als Favoriten
   
   

   C#-Quellcode

   1. //URI Route des Controllers, Wenn [Controller] verwendet wird dann ist es api/<Klassenname - Controller>
   2. [Route("api/[Controller]")]
   3. public class CustomersController : Controller
   4. {
   5. //Operationen Route unter Name angeben
   6. [HttpGet(Name = Routes.CUSTOMERS_GETAllCUSTOMER)]
   7. public IActionResult Get()
   8. {
   9. //Neues Siren Objekt erstellen
   10. var siren = new Siren();
   12. //Verwendete Klassen hinzufügen
   13. siren.Class.Add("Customers");
   14. siren.Class.Add("Collection");
   17. foreach (var customer in CustomerRepository.GetAll())
   18. {
   19. //Entities befüllen und in Siren geben, mit Self-Link
   20. var entity = new EmbeddedRepresentation();
   21. entity.Class.Add("CustomerOverview");
   22. entity.Properties.Add(new Property { Name = "Name", Value = customer.Name });
   23. entity.Properties.Add(new Property { Name = "LastContact", Value = customer.LastContact });
   24. entity.Properties.Add(new Property { Name = "IsFavorite", Value = customer.IsFavorite });
   25. //Self Link hinzufügen
   26. entity.Links.Add(new Link
   27. {
   28. Relation = new List<string> { "self" },
   29. Href = Url.Link(Routes.CUSTOMERS_GETCUSTOMER, new { id = customer.Id })
   30. });
   31. siren.Entities.Add(entity);
   32. }
   34. //Aktionen hinzufügen
   35. siren.Links.Add(new Link
   36. {
   37. Relation = new List<string> { "self" },
   38. //Nur Null wählen wenn keinerlei Pfad Parameter wie api/Customer/1 benötigt werden
   39. Href = Url.Link(Routes.CUSTOMERS_GETAllCUSTOMER, null)
   40. });
   41. return Ok(siren);
   42. }
   44. //Hier wird die ID des Kunden benötigt
   45. [HttpGet("{id}", Name = Routes.CUSTOMERS_GETCUSTOMER)]
   46. public IActionResult Get(int id)
   47. {
   48. try
   49. {
   50. //Objekt anhand von ID aus Repo holen
   51. var customer = CustomerRepository.Get(id);
   53. //Siren Objekt erstellen
   54. var siren = new Siren();
   55. // Verwendete Klaasen hinzufügen
   56. siren.Class.Add("Customer");
   58. //Properties Hinzufügen
   59. siren.Properties.Add(new Property { Name = "Name", Value = customer.Name });
   60. siren.Properties.Add(new Property { Name = "LastContact", Value = customer.LastContact });
   61. siren.Properties.Add(new Property { Name = "IsFavorite", Value = customer.IsFavorite });
   63. // Self-Link zur Methode hinzufügen
   64. siren.Links.Add(new Link
   65. {
   66. Relation = new List<string> { "self" },
   67. Href = Url.Link(Routes.CUSTOMERS_GETCUSTOMER, new { id = customer.Id })
   68. });
   70. //Alle Sonstigen Methoden hinzufügen
   71. if (!customer.IsFavorite)
   72. {
   73. siren.Actions.Add(new Action
   74. {
   75. Name = "MarkAsFavorite",
   76. Method = "POST",
   77. Href = Url.Link(Routes.CUSTOMERS_MARKASFAVORITE, null)
   78. });
   79. }
   81. siren.Actions.Add(new Action
   82. {
   83. Name = "Move",
   84. Method = "POST",
   85. Href = Url.Link(Routes.CUSTOMERS_MOVE, new { id = customer.Id })
   86. });
   88. return Ok(siren);
   89. }
   90. catch (KeyNotFoundException)
   91. {
   92. return NotFound();
   93. }
   94. }
   96. //Einfügen eines neuen Customers über POST
   97. [HttpPost]
   98. public void Post([FromBody]Customer customer)
   99. {
   100. CustomerRepository.Add(customer);
   101. }
   102. }
   104. public static class Routes
   105. {
   106. public const string CUSTOMERS_MARKASFAVORITE = "CUSTOMERS_MARKASFAVORITE";
   107. public const string CUSTOMERS_GETAllCUSTOMER = "CUSTOMERS_GETAllCUSTOMER";
   108. public const string CUSTOMERS_GETCUSTOMER = "CUSTOMERS_GETCUSTOMER";
   110. }
   
   
5. Erstellen von Controllern für spezifische Operationen auf einen Objekt der Domäne:

Das wars auch schon :), damit ist ein erstes sehr grundlegendes Beispiel einer REST-API fertig.
Wie versprochen hänge ich unten noch die beiden Klassen an.