Download to read offline
![Example: Book Store inventory
• HATEOAS - Hypermedia as the
Engine of Application State
• The essential part of the "uniform
interface"
• API is discovered dynamically
through interaction with the service
Adhere industry standards
{
"class": [ "order" ],
"properties": {
"orderNumber": 42,
"itemCount": 3,
"status": "pending"
},
"entities": [
{
"class": [ "items", "collection" ],
"rel": [ "http://x.io/rels/order-items" ],
"href": "http://api.x.io/orders/42/items"
},
{
"class": [ "info", "customer" ],
"rel": [ "http://x.io/rels/customer" ],
"properties": {
"customerId": "pj123",
"name": "Peter Joseph"
},
"links": [
{ "rel": [ "self" ], "href": "http://api.x.io/customers/pj123" }
]
}
],
"actions": [
{
"name": "add-item",
"title": "Add Item",
"method": "POST",
"href": "http://api.x.io/orders/42/items",
"type": "application/x-www-form-urlencoded",
"fields": [
{ "name": "orderNumber", "type": "hidden", "value": "42" },
{ "name": "productCode", "type": "text" },
{ "name": "quantity", "type": "number" }
]
}
],
"links": [
{ "rel": [ "self" ], "href": "http://api.x.io/orders/42" },
{ "rel": [ "previous" ], "href": "http://api.x.io/orders/41" },
{ "rel": [ "next" ], "href": "http://api.x.io/orders/43" }
]
}
{
"orderNumber": 42,
"itemCount": 3,
"status": "pending"
}](https://image.slidesharecdn.com/nbu-buildingsoftwarewebapi-170424091916/85/Building-Software-Backend-Web-API-17-320.jpg)
Uploaded byAlexander Goida
Building Software Backend (Web API)
The document is a presentation on building software APIs, focusing on RESTful services, principles, and practical examples like a bookstore inventory system. It discusses the architecture of web services, standards such as OpenAPI and OData, and design considerations for creating robust APIs. Key topics include defining domain models, resources, adhering to industry standards, and testing methodologies.
More Related Content
Similar to Building Software Backend (Web API)
Building Software Backend (Web API)
- 1. UK: +44 (0)8450 571 234 US: +1 203 838 3700 Europe, Middle East & Africa: +00 971 5033 502964 Australia: +61420237512 www.fourth.com Building Software WebAPI Design Guide Date: 24-Apr-2017 Alexander Goida
- 2. Presenter Alexander Goida Senior SoftwareEngineer – StarChef Knowledge Sharing facilitator – Sofia Almost 2 years in Fourth and 14 years in IT as Software Developer
- 3. Topics for today •Web Services overview • RESTful service principles • Example: Book Store inventory • Define Domain model • Define resources • Adhere IT standards • Design classes • Testing
- 4. Web Services overview Thereare no rules of architecture for a castle in the clouds.
- 5. Web Services overview:Simplified architecture
- 6. Web Services overview:WCF protocols WCF Services • Supports multiple protocols • Strong typing • Very configurable • Complex for heterogeneous system • Supports GET, POST by default
- 7. Web Services overview:Web API protocols Web API Services • Simple • Supports all HTTP verbs & features • Supports MVC features • Supports only HTTP protocol • No strong typing
- 8. Web Services overview:Architectural styles • Endpoint contains routine name • Good when exposing existing routines to web • Good when server keeps the state • Simpler to design • Endpoint contains resource name • Good for new systems • Good for stateless operations • Good for Javascript clients • Closer to web
- 9. RESTful service principles Thereare three constants in life... change, choice and principles.
- 10. RESTful service principles 1.Uniform Interface 2. Stateless Interactions 3. Cacheable 4. Client-Server 5. Layered System 6. Code on Demand (optional)
- 11. RESTful service principles Level0: Swamp of POX • Plain Old XML • XML-RPC, SOAP Level 1: Resources Level 2: HTTP verbs • All verbs • HTTP Status Codes Level 3: Hypermedia controls • HATEOAS • Dynamic discovery of endpoints Richardson Maturity Model Ideal RESTful service Most of REST services
- 12. Example: Book Storeinventory The practice killed hedgehog who knew how to eat cactus safely
- 13. Example: Book Storeinventory • Simple business model • RESTful service (level 2) • Supports • CRUD operations • OData queries • Documented (Swagger) • Versioned • Source code at GitHub
- 14. Example: Book Storeinventory Domain Model Bounded contexts Resources Service granularity Standards HATEOAS Open API OData Versioning Security Basic Authentication OAuth Classes SOLID Software Patterns Designing steps & Considerations 1 2 3 4 5
- 15. Example: Book Storeinventory • Bounded context • Aggregation root • Entity • Value object Define Domain Model
- 16. Example: Book Storeinventory • Use your Domain model • Define “language” to your API • Root & Dependent resources • GET /authors • DELETE /authors/ID • GET /authors/ID/books • Anti-patterns • GET /authors/delete?id=GUID • POST /GetPublisherDetails • POST /author/create Define Resources
- 17. Example: Book Storeinventory • HATEOAS - Hypermedia as the Engine of Application State • The essential part of the "uniform interface" • API is discovered dynamically through interaction with the service Adhere industry standards { "class": [ "order" ], "properties": { "orderNumber": 42, "itemCount": 3, "status": "pending" }, "entities": [ { "class": [ "items", "collection" ], "rel": [ "http://x.io/rels/order-items" ], "href": "http://api.x.io/orders/42/items" }, { "class": [ "info", "customer" ], "rel": [ "http://x.io/rels/customer" ], "properties": { "customerId": "pj123", "name": "Peter Joseph" }, "links": [ { "rel": [ "self" ], "href": "http://api.x.io/customers/pj123" } ] } ], "actions": [ { "name": "add-item", "title": "Add Item", "method": "POST", "href": "http://api.x.io/orders/42/items", "type": "application/x-www-form-urlencoded", "fields": [ { "name": "orderNumber", "type": "hidden", "value": "42" }, { "name": "productCode", "type": "text" }, { "name": "quantity", "type": "number" } ] } ], "links": [ { "rel": [ "self" ], "href": "http://api.x.io/orders/42" }, { "rel": [ "previous" ], "href": "http://api.x.io/orders/41" }, { "rel": [ "next" ], "href": "http://api.x.io/orders/43" } ] } { "orderNumber": 42, "itemCount": 3, "status": "pending" }
- 18. Example: Book Storeinventory • Open API Specification (Swagger 2.0) • JSON base specification • Language-agnostic specification of RESTful APIs • Server proxy can be auto-generated • Swashbuckle automates for .NET with UI Adhere industry standards
- 19. Example: Book Storeinventory • OData – Open Data Protocol to query data in RESTful APIs • Deal with a lot of data • Filtering, sorting and paging Adhere industry standards Query Option Sample Description $filter /authors?$filter=Name eq ‘name’ /authors?$filter=contains(Name, ‘name') filter a collection of resources that are addressed by a request $orderby /authors?$orderby=Name desc request resources in asc or desc order $select /authors?$select=Name requests a limited set of properties for each entity $skip & $top /authors?$skip=5 /authors?$top=5 request a limited number of records
- 20. Example: Book Storeinventory • Versioning: • MAJOR for breaking changes • MINOR for backwards-compatible changes • PATCH for backwards-compatible bug fixes • In general only MAJOR is used Adhere industry standards Style Sample URL /api/v2/authors Custom header /api/authors Header: api-version=2 Accept header Accept: application/vnd.bookstore.v2+json Also Possible: • /api/foo?api-version=1.0 • /api/foo?api-version=2.0-Alpha • /api/foo?api-version=2015-05-01.3.0 • /api/v2.0-Alpha/foo • /api/v2015-05-01.3.0/foo
- 21. Example: Book Storeinventory • SOLID • Use constructor for injecting • Low coupling, High cohesion • KISS, YAGNI, DRY • Patterns • Data Mapper • Dependency Injection • Repository • Unit Of Work • Anti-patterns • Service locator • God object Design classes
- 22. Example: Book Storeinventory Design classes
- 23. Testing Test less, buttests smarter
- 24. Testing • Vision • Defendyour solution with tests • Consider use cases of methods • Test requirements, not everything • The less integration tests, the better • Unit testing • AAA style • Isolated tests • Better to test through public methods • Integration testing • In-Memory hosting is simple • Check routing and database • Manual testing • Tools Swagger UI, Postman
- 25. Glossary • WCF • WindowsCommunication Foundation, a framework for building service-oriented application software • REST • Representational State Transfer, the architectural style which allows clients manipulate web resources using stateless operations • HATEOAS • Hypermedia as the Engine of Application State, a constraint of RESTful style which allows a client to interact with a service through hypermedia provided dynamically • SOAP • Simple Object Access Protocol, a protocol specification based on XML for exchanging structured information independent of language and platforms • RPC • Remote Procedure Call, an inter-process communication technique in networked computing • Named Pipes • An inter-process communication technique within same machine • OData • Open Data Protocol, an open protocol which allows the creation and consumption of queryable APIs
- 26. Reading Material &Sources 1. Modern Web App Architecture (web link) 2. Chapter 21: Designing Web Applications (web link) 3. Difference between WCF and Web API and WCF REST and Web Service (web link) 4. Do you really know why you prefer REST over RPC? (web link) 5. What Is REST? (web link) 6. Richardson Maturity Model (web link) 7. API design (web link) 8. Choosing a hypermedia type for your API (web link) 9. Choosing a Transport (web link) 10. Best Practices for Designing a Pragmatic RESTful API (web link) 11. Adding Swagger to Web API project (web link) 12. Demystify Web API Versioning (web link) 13. Introduction to OData (video) 14. OData tutorial (web link)
- 27. Final questions? Too muchinformation? But this is just the beginning!