So you're building a Rails API and you want to do it right--following RESTful best practices, with endpoints that can sideload related resources, paginate and filter with grace. The JSON API Specification (jsonapi.org) aims to help you do this without spending a month bikeshedding or reinventing the wheel. But does it really work? Based on my experience using it in my last project, this talk will help you decide whether to use it and how to do so with Rails.

1. Building a
JSON API Spec
Rails API
with the

2. billing
service
service
managing
ads
add items
front end
user facing
show & update
accounts
external
payment provider
new
to autobill

3. book data
service
front end
user facing
show me
books
update
books
front end
admin

4. API goals:

5. flexible
API goals:

6. consistent
flexible
API goals:

7. consistent
flexible
fast
API goals:

8. enter
JSON API

9. API goals:

10. flexible
API goals:

11. consistent
flexible
API goals:

12. consistent
flexible
fast
API goals:

13. bikeshedding

14. generalized
libraries &
tooling

15. made it?
Who

16. Whyam I
about it?
talking

17. How does it
work?

18. strict requirements:
including related
resources
creating & updating
resources
fetching resources
manipulating
relationships

19. paginationsorting
filtering
sparse fieldsets
some requirements/guidelines:
including links
errors

20. up to you:
URL design
how resources map
to actual stored data
authentication
authorization

22. Fetching a resource: GET /books/2

23. Fetching a resource: GET /books/2
JSON API document

24. Fetching a resource: GET /books/2
resource object

25. Fetching a resource: GET /books/2
resource identifier
objects

27. Fetching a collection of resources: GET /books

28. Fetching a collection of resources: GET /books
array of resource objects

30. Using include: GET /books?include=author,editorial_tags

31. Using include: GET /books?include=author,editorial_tags

32. Using include: GET /books?include=author,editorial_tags

33. why
not
nest?

35. GET /books?include=tags,author.tags
Including multiple levels

37. GET /books?include=author
&fields[authors]=name
&fields[books]=title
Sparse fieldsets:

38. Creating a resource:
POST /books

39. PATCH /books/2
Updating a resource:

40. DELETE /books/2
Deleting a resource:

41. Links

42. Links
resource level links object

43. Links
resource level links object
relationship level links object

44. https://example.com/books/1/relationships/author
https://example.com/books/1/author
related link:
self link:
relationship links:

45. PATCH
/books/2/relationships/author

46. paginationsorting
filtering
sparse fieldsets
some requirements/guidelines:
including links
errors

47. JSON API
Ruby on Rails
+

48. convention
configuration

49. Active Model Serializers
JSONAPI::Resources
vs

50. just serialization
full server side flow
vs

51. more control
more magic
vs

52. lots more libraries!
http://jsonapi.org/implementations/#client-libraries-ruby
http://jsonapi.org/implementations/#server-libraries-ruby
https://github.com/fotinakis/jsonapi-serializers

53. should
youuse it?

54. bikeshedding

55. What can go in an error object?

56. What can go in an error object?
id and/or links and/or status
and/or meta and/or detail
and/or code and/or title and/
or meta and/or source (with a
pointer and/or a parameter)

57. the bike shed
the nuclear plant

58. ???
the bike shed
the nuclear plant

59. limitations:
creating a resource
and its relationships
at the same time
multiple operations
in one request

60. limitations:
creating a resource
and its relationships
at the same time
multiple operations
in one request
current

61. widely applicable
effectivesimple

62. widely applicable
effectivesimple
pick two?

63. nothing
free
in life is

64. API goals:

65. flexible
API goals:

66. consistent
flexible
API goals:

67. consistent
flexible
fast
API goals:

68. initial
larger
cost
payoff?term
long-term

69. consistency & flexibility
large collections
of data with
in one request
yes
have time
up front
to investrelationships
larger team
priorities:

70. need multi
operation
requests
easy to update
clients
no
simplicity & speed
priorities:
don’t want
dependencies

71. should
youuse it?

72. you

73. www.bookbub.com/careers
@SonjaBPeterson
also, we’re hiring!
Questions?
on twitter