Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for...
Transcript of Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for...
![Page 1: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/1.jpg)
Writing an APIwith Swift 3 on Linux
Rob Allen
akrabat.com ~ @akrabat ~ April 2017
![Page 2: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/2.jpg)
Swift?Swift is a general-purpose programming language built using amodern approach to safety, performance, and software designpatterns.
swift.org
Rob Allen ~ @akrabat
![Page 3: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/3.jpg)
Open Source• Created by Apple• Apache 2 license• Source code on GitHub• Swift-evolution: open design of new features
Rob Allen ~ @akrabat
![Page 4: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/4.jpg)
Cross Platform• Runs on Linux (x86) and all Apple OSs• Ports in progress: Android, Linux(ARM), FreeBSD, Windows• Libraries: Standard library, Foundation, Dispatch & XCTest
Rob Allen ~ @akrabat
![Page 5: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/5.jpg)
Performance
Rob Allen ~ @akrabat
![Page 6: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/6.jpg)
Memory
Rob Allen ~ @akrabat
![Page 7: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/7.jpg)
Major featuresStrong typing Custom operatorsType inference TuplesOptionals GenericsClosures Interoperable with C
Rob Allen ~ @akrabat
![Page 8: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/8.jpg)
Safety• Type safety• Prefer constants over variables• Variables are always initialized before use• Optionals: variables can never be nil
Rob Allen ~ @akrabat
![Page 9: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/9.jpg)
Rock-Paper-Scissors 1 import Foundation 2
3 let shapes = ["rock", "paper", "scissors"] 4
5 for count in 1...3 { 6 print(count)
7 sleep(1)
8 }
9
10 srandom(UInt32(NSDate().timeIntervalSince1970))
11 let chosenShape = random() % shapes.count12 print(player[chosenShape]);
Rob Allen ~ @akrabat
![Page 10: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/10.jpg)
Result$ swift rock-paper-scissors.swift
1
2
3
scissors
Rob Allen ~ @akrabat
![Page 11: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/11.jpg)
StructsSwift's value objects 1 struct Money { 2 enum Currency { case GBP, EUR, USD } 3 let money: (Decimal, Currency) 4
5 init (amount: Decimal, currency: Currency) { 6 money = (amount, currency)
7 }
8
9 var amount: String {10 get { return money.0.round(to: 2) }11 }
12 }
Rob Allen ~ @akrabat
![Page 12: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/12.jpg)
StructsUsage:1 let fivePounds = Money(amount: 5.20, currency: .GBP)2 print(fivePounds.amount)
Compile and run:$ swift test.swift
5.20
Rob Allen ~ @akrabat
![Page 13: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/13.jpg)
ClassesSwift's reference objects (& you can inherit!)1 class Child {2 var name: String3 var age: Int4
5 init (name: String, age: Int) {6 self.name = name7 self.age = age8 }
9 }
Rob Allen ~ @akrabat
![Page 14: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/14.jpg)
Classes1 let ben = Child(name: "Ben", age: 12)2 let jon = ben3 jon.name = "Jon"
4
5 print(ben.name)
6 print(jon.name)
$ swift test.swift
Jon
Jon
Rob Allen ~ @akrabat
![Page 15: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/15.jpg)
Protocols• Blueprint of methods & properties, etc that suit a task• Protocols are adopted by classes & structures
1 protocol Shareable { 2 func toJSON() -> String 3 }
4
5
6 extension Money : Shareable { 7 func toJSON() -> String { 8 // implement here 9 return json10 }
11 }
Rob Allen ~ @akrabat
![Page 16: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/16.jpg)
Rob Allen ~ @akrabat
![Page 17: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/17.jpg)
Learn the language
Rob Allen ~ @akrabat
![Page 18: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/18.jpg)
So what does it take to write SwiftAPIs on Linux?
Rob Allen ~ @akrabat
![Page 19: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/19.jpg)
Steps to Swift APIs1. Environment2. Framework3. Write an API!4. Deploy
Rob Allen ~ @akrabat
![Page 20: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/20.jpg)
Environment
Rob Allen ~ @akrabat
![Page 21: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/21.jpg)
Environment• Ubuntu Linux 16.04 (or 14.04)• Local development
• Docker• Vagrant• macOS
Rob Allen ~ @akrabat
![Page 22: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/22.jpg)
Swiftenv version manager• Simple install of releases and snapshots$ swiftenv install 3.1
• Scoped to project$ cd my-project
$ swiftenv local 3.1
# creates: .swift-version
Rob Allen ~ @akrabat
![Page 23: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/23.jpg)
Swift Package ManagerThe Swift Package Manager is a tool for managing the distributionof Swift code. It’s integrated with the Swift build system to automatethe process of downloading, compiling, and linking dependencies.
swift.org
Rob Allen ~ @akrabat
![Page 24: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/24.jpg)
Swift Package Manager• Dependency manager
• Fetches & builds dependencies from Git• Controlled via Package.swift
Rob Allen ~ @akrabat
![Page 25: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/25.jpg)
Swift Package Manager• Dependency manager
• Fetches & builds dependencies from Git• Controlled via Package.swift
• Part of Swift cli:• swift package
• swift build
• swift test
Rob Allen ~ @akrabat
![Page 26: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/26.jpg)
Create a new project$ cd my-project
$ swift package init --type executable
Creating executable package: my-project
Creating Package.swift
Creating .gitignore
Creating Sources/
Creating Sources/main.swift
Creating Tests/
Rob Allen ~ @akrabat
![Page 27: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/27.jpg)
Package.swift1 import PackageDescription2
3 let package = Package(4 name: "my-project"
5 )
Rob Allen ~ @akrabat
![Page 28: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/28.jpg)
Add dependencies 1 import PackageDescription 2
3 let package = Package( 4 name: "my-project",
5 dependencies: [
6 .Package(url: "https://github.com/jatoben/CommandLine",
7 majorVersion: 2, minor: 2),
8 .Package(url: "https://github.com/stormpath/Turnstile",
9 majorVersion: 1),
10 ]
11 )
Rob Allen ~ @akrabat
![Page 29: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/29.jpg)
Choose a web framework
Rob Allen ~ @akrabat
![Page 30: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/30.jpg)
Web frameworks
Rob Allen ~ @akrabat
![Page 31: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/31.jpg)
Pick the one that fits you best(I like Kitura)
Rob Allen ~ @akrabat
![Page 32: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/32.jpg)
Kitura1 import PackageDescription2
3 let package = Package(4 name: "HelloWorld",
5 dependencies: [
6 .Package(url: "https://github.com/IBM-Swift/Kitura.git",
7 majorVersion: 1, minor: 7),
8 ]
9 )
Rob Allen ~ @akrabat
![Page 33: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/33.jpg)
Hello world 1 // Sources/main.swift 2 import Kitura 3 import SwiftyJSON 4
5 let router = Router() 6 router.get("/hello") { request, response, next in 7 response.status(.OK).send(json: JSON(["hello" : "world"]))
8 next()
9 }
10
11 Kitura.addHTTPServer(onPort: 8090, with: router)
12 Kitura.run()
Rob Allen ~ @akrabat
![Page 34: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/34.jpg)
Hello world 1 $ curl -i -X GET http://localhost:8090/hello
2 HTTP/1.1 200 OK
3 Date: Sun, 09 Oct 2016 08:26:34 GMT
4 Content-Length: 22
5 Content-Type: application/json
6 Connection: Keep-Alive
7 Keep-Alive: timeout=60, max=99
8
9 {
10 "hello": "world"
11 }
Rob Allen ~ @akrabat
![Page 35: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/35.jpg)
Writing an API
Rob Allen ~ @akrabat
![Page 36: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/36.jpg)
Primary aspects of a RESTful API• URI for each resource: https://localhost:8090/books/14• HTTP methods are the set of operations allowed for the resource• Correct use of status codes• Media type used for representations of the resource• The API must be hypertext driven
Rob Allen ~ @akrabat
![Page 37: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/37.jpg)
HTTP methods & URIs
Rob Allen ~ @akrabat
![Page 38: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/38.jpg)
HTTP methodsMethod Used for Idempotent?GET Retrieve data YesPUT Change data YesDELETE Delete data YesPOST Change data NoPATCH Update data No
Send 405 Method Not Allowed or 404 Not Found if cannot honour
Rob Allen ~ @akrabat
![Page 39: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/39.jpg)
A URI for each resource1 router.get("/books", handler: listBooksHandler)
2 router.post("/books", handler: createBookHandler)
3
4 router.get("/books/:id", handler: getBookHandler)
5 router.put("/books/:id", handler: replaceBookHandler)
6 router.patch("/books/:id", handler: updateBookHandler)
7 router.delete("/books/:id", handler: deleteBookHandler)
Rob Allen ~ @akrabat
![Page 40: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/40.jpg)
Dynamic routes 1 router.get("/books/:id") { request, response, next in 2
3 guard let id: String = request.parameters["id"] else { 4 response.status(.notFound)
5 .send(json: JSON(["error": "Not Found"]))
6 next()
7 }
8
9 // id is now valid10 // do things and set up response11 next()
12 }
Rob Allen ~ @akrabat
![Page 41: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/41.jpg)
Reading dataQuery parameters:1 router.get("/books") { request, response, next in2
3 // e.g. http://localhost/books?filter=new4 let filter = request.quaryParameters["filter"] ?? ""
Body data:1 router.post("/books") { request, response, next in2
3 let data = try request.readString() ?? ""4 // decode data appropriately
Rob Allen ~ @akrabat
![Page 42: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/42.jpg)
JSON & form body dataAdd BodyParser middleware:
1 router.all("/books", middleware: BodyParser())
Retrieve parsed body in callback:1 guard let parsedBody = request.body else { next(); return }2
3 switch(parsedBody) {4 case .json(let jsonBody):5 // do something with jsonBody6 case .multipart(let parts):7 // do something with form data8 default: break9 }
Rob Allen ~ @akrabat
![Page 43: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/43.jpg)
Rob Allen ~ @akrabat
![Page 44: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/44.jpg)
Content-type handling
Rob Allen ~ @akrabat
![Page 45: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/45.jpg)
Content negotiationCorrectly parse the request
• Read the Content-Type header• Decode body appropriately
Correctly create the response
• Read the Accept header• Set the Content-Type header
Raise 415 Unsupported media type status if unsupported
Rob Allen ~ @akrabat
![Page 46: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/46.jpg)
Reading headers in Kitura 1 router.get("/books/:id") { request, response, next in 2
3 let contentType = request.headers["Accept"] ?? "" 4
5 if contentType.range(of: "json") == nil { 6 // send 415 7 Log.info("Invalid Media Type: \(contentType)") 8 response.status(.unsupportedMediaType)
9 response.send(json: JSON(["error": "Unsupported Media Type"]))
10 next()
11 }
12
13 // Okay to continue
Rob Allen ~ @akrabat
![Page 47: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/47.jpg)
Hypermedia• Media type used for a representation• The link relations between representations and/or states• Important for discoverability
Rob Allen ~ @akrabat
![Page 48: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/48.jpg)
Paginate collectionsMobile devices don't have that much memory!
• Hypermedia link relations: first, last, next & prev relations• Include count of items sent• Include total count of items too
Rob Allen ~ @akrabat
![Page 49: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/49.jpg)
Media types matterWith application/json you abdicate responsibility.A more structured media type:
• Tells the client how to interpret the data• Enforces structure of the payload• Informs on what the payload data means
Rob Allen ~ @akrabat
![Page 50: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/50.jpg)
Hal+Json• Resources
• State (standard data)• Links (to URIs)• Embedded resources (within this resource)
• Links• Target (URI)• Relation (i.e. the name of the link)
Rob Allen ~ @akrabat
![Page 51: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/51.jpg)
Hal+Json1 Content-Type: application/hal+json
2
3 {
4 "title": "The Hunger Games",
5 "isbn": "9780439023528"
6 }
Rob Allen ~ @akrabat
![Page 52: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/52.jpg)
Hal+Json1 Content-Type: application/hal+json
2
3 {
4 "title": "The Hunger Games",
5 "isbn": "9780439023528",
6 "_links": {
7 "self": { "href": "http://localhost:8090/books/1" }
8 }
9 }
Rob Allen ~ @akrabat
![Page 53: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/53.jpg)
Hal+Json 1 Content-Type: application/hal+json
2
3 {
4 "title": "The Hunger Games",
5 "isbn": "9780439023528",
6 "_links": {
7 "self": { "href": "http://localhost:8090/books/1" }
8 },
9 "_embedded": {
10 "author": {
11 "name": "Suzanne Collins",
12 "_links": {
13 "self": { "href": "http://localhost:8090/authors/1" }
14 }
15 }
Rob Allen ~ @akrabat
![Page 54: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/54.jpg)
Rob Allen ~ @akrabat
![Page 55: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/55.jpg)
In Kitura 1 var json = book.toJSON() 2
3 json["_links"] = JSON(["self": ["href": baseURL + "/books/" + book.id]])
4
5 json["_embedded"]["author"] = book.getAuthor().toJSON()
6 json["_embedded"]["author"]["_links"] = JSON(["self":
7 ["href": baseURL + "/authors/" + book.getAuthor().id]])
8
9 response.status(.OK).send(json: json)
10 response.headers["Content-Type"] = "application/hal+json"
11 next()
(or use a library!)
Rob Allen ~ @akrabat
![Page 56: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/56.jpg)
Error handling
Rob Allen ~ @akrabat
![Page 57: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/57.jpg)
Error handling• Error representations are first class citizens
• Correct content-type• Uses correct HTTP status code
Rob Allen ~ @akrabat
![Page 58: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/58.jpg)
Error handling• Error representations are first class citizens
• Correct content-type• Uses correct HTTP status code
• Provides application error code & human readable message• End user needs a short, descriptive message• Client developer needs detailed information• Client application needs an error code
Rob Allen ~ @akrabat
![Page 59: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/59.jpg)
HTTP Problem (RFC 7807)HTTP/1.1 503 Service Unavailable
Content-Type: application/problem+json
Content-Language: en
{
"status": 503, "type": "https://example.com/service-unavailable", "title": "Could not authorise user due to an internal problem - try later.", "detail": "The authentication service is down for maintenance.", "instance": "https://example.com/maintenance-schedule/2016-08-30", "error_code": "AUTHSERVICE_UNAVAILABLE"}
Rob Allen ~ @akrabat
![Page 60: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/60.jpg)
Deployment
Rob Allen ~ @akrabat
![Page 61: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/61.jpg)
Deployment• Any Ubuntu Linux server
• Your own• Heroku / Bluemix / AWS
Rob Allen ~ @akrabat
![Page 62: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/62.jpg)
HerokuUse Kyle Fuller's buildpack:$ heroku create --buildpack https://github.com/kylef/heroku-buildpack-swift.git
Creating app... done, ⬢ gentle-sands-13696
Setting buildpack to https://github.com/kylef/heroku-buildpack-swift.git... done
https://gentle-sands-13696.herokuapp.com/
| https://git.heroku.com/gentle-sands-13696.git
$ git remote add heroku https://git.heroku.com/gentle-sands-13696.git
$ heroku ps:scale web=1
Rob Allen ~ @akrabat
![Page 63: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/63.jpg)
Add two files.swift-version
3.1
Procfile:web: HelloWorld --workers 1 --bind 0.0.0.0:$PORT
Rob Allen ~ @akrabat
![Page 64: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/64.jpg)
Environment variablesYou will be running on $PORT, not 8090:1 Kitura.addHTTPServer(onPort: 8809, with: router)
becomes:1 let env = ProcessInfo.processInfo.environment2 let port = Int(env["PORT"] ?? "") ?? 80903 Kitura.addHTTPServer(onPort: port, with: router)
Rob Allen ~ @akrabat
![Page 65: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/65.jpg)
Deploy$ git push heroku master
Counting objects: 19, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (7/7), done.
Writing objects: 100% (19/19), 3.12 KiB | 0 bytes/s, done.
Total 19 (delta 0), reused 0 (delta 0)
remote: Compressing source files... done.
remote: Building source:
[... install Swift & run swift build ...]
remote: ---> Launching...
remote: Released v6
remote: https://gentle-sands-13696.herokuapp.com/ deployed to Heroku
remote:
remote: Verifying deploy... done.
Rob Allen ~ @akrabat
![Page 66: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/66.jpg)
Run$ curl -i https://gentle-sands-13696.herokuapp.com/hello
HTTP/1.1 200 OK
Server: Cowboy
Connection: keep-alive
Content-Type: application/json
Date: Mon, 10 Apr 2017 18:03:23 GMT
Content-Length: 22
Via: 1.1 vegur
{
"hello": "world"
}
Rob Allen ~ @akrabat
![Page 67: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/67.jpg)
To sum up
Rob Allen ~ @akrabat
![Page 68: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/68.jpg)
ResourcesWebsites:
• https://swift.org• http://www.kitura.io• https://akrabat.com/category/swift/• https://swift.org/community/#mailing-lists
Newsletters:
• https://swiftweekly.github.io• https://swiftnews.curated.co
Rob Allen ~ @akrabat
![Page 69: Writing an API - akrabat.com · Swift Package Manager The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system](https://reader030.fdocuments.net/reader030/viewer/2022040307/5ed2d6b6db6651121404a5c4/html5/thumbnails/69.jpg)
Thank you!
Rob Allen ~ akrabat.com ~ @akrabat