RESTful API - Best Practices.
This is a modal window.
The media could not be loaded, either because the server or network failed or because the format is not supported.
Formal Metadata
| Title |
| |
| Title of Series | ||
| Part Number | 140 | |
| Number of Parts | 169 | |
| Author | ||
| License | CC Attribution - NonCommercial - ShareAlike 3.0 Unported: You are free to use, adapt and copy, distribute and transmit the work or content in adapted or unchanged form for any legal and non-commercial purpose as long as the work is attributed to the author in the manner specified by the author or licensor and the work or content is shared also in adapted form only under the conditions of this | |
| Identifiers | 10.5446/21179 (DOI) | |
| Publisher | ||
| Release Date | ||
| Language |
Content Metadata
| Subject Area | ||
| Genre | ||
| Abstract |
|
EuroPython 2016140 / 169
1
5
6
7
10
11
12
13
18
20
24
26
29
30
31
32
33
36
39
41
44
48
51
52
53
59
60
62
68
69
71
79
82
83
84
85
90
91
98
99
101
102
106
110
113
114
115
118
122
123
124
125
132
133
135
136
137
140
143
144
145
147
148
149
151
153
154
155
156
158
162
163
166
167
169
00:00
SoftwareCodeSoftware developerLine (geometry)Shared memoryExtension (kinesiology)Representational state transfer
00:32
Software developerThermal expansionWeb pageCASE <Informatik>Multiplication signNatural numberINTEGRALInternet service providerComputer animation
00:55
Projective planeINTEGRALRight angleLevel (video gaming)Module (mathematics)Different (Kate Ryan album)Event horizonComputer animation
01:14
INTEGRALInternet service providerInformation technology consultingProduct (business)Functional (mathematics)Task (computing)State of matterComputer animation
01:44
Type theoryInformationPoint (geometry)View (database)Object (grammar)Field (computer science)Event horizonPower (physics)TelecommunicationRange (statistics)Data storage deviceRegular graphData typeClient (computing)String (computer science)Electronic visual displayElectronic mailing list
03:05
WindowInternet service providerEvent horizonTask (computing)Process (computing)Link (knot theory)AdditionDatabaseMultiplication signFrame problemComputer animation
03:51
IP addressPoint (geometry)Instance (computer science)Enterprise architectureQuery languageSoftware developerSoftware testingMultiplication signInternet service provider
04:22
HoaxSoftware testingInternet service providerMultiplication signKey (cryptography)Integrated development environmentResultantRankingEvent horizonDemo (music)Product (business)Web pageDatabase
05:18
Representational state transferSystem programmingHypermediaSoftwareSoftware architectureWorld Wide WebConstraint (mathematics)Server (computing)Client (computing)CodeInterface (computing)Physical systemInformationRight angleDependent and independent variablesContext awarenessSanitary sewerState of matterRepresentation (politics)Message passingWeb serviceFirewall (computing)Gateway (telecommunications)Computer configurationComponent-based software engineeringScalabilityTelecommunicationLevel (video gaming)Computer programWorld Wide Web ConsortiumGUI widgetModel theoryOffice suiteINTEGRALGame controllerACIDOrder (biology)Level (video gaming)Capability Maturity ModelServer (computing)Cartesian coordinate systemInformationDesign by contractUniformer RaumMultiplication signFrequencyRepresentational state transferMathematicsElectronic program guideCodeSoftware architectureCache (computing)Client (computing)Web serviceRule of inferenceMereologyFunctional (mathematics)SoftwareWeb browserPhysical systemConstraint (mathematics)Interactive televisionUser interfaceData storage devicePortable communications deviceDependent and independent variablesData structureTelecommunicationFlow separationDivision (mathematics)Type theoryEvent horizonConnected spaceInternet service providerSet (mathematics)HypermediaInterface (computing)Category of beingState of matterLogicHeat transferLocal ringWebsiteMessage passingScalabilityStructural loadMultiplicationProduct (business)Presentation of a groupSource codeStatement (computer science)Logic gateNeuroinformatikScripting languageGradientFood energyEndliche ModelltheorieRight angleConstructor (object-oriented programming)Computer configurationAreaCivil engineeringVector spaceGroup actionPoint (geometry)Connectivity (graph theory)Descriptive statisticsComputer animationProgram flowchart
10:46
Set (mathematics)CASE <Informatik>Patch (Unix)Representational state transferData structureLogicResultantElectronic mailing listImplementationEvent horizonMixed realityCorrespondence (mathematics)Mathematical singularityCASE <Informatik>Operator (mathematics)Parameter (computer programming)QuicksortOrder (biology)ConvolutionFinitismusMathematical analysisSummierbarkeitDatabaseComputer animation
12:11
Electronic mailing listEvent horizonReading (process)Patch (Unix)Object (grammar)ResultantFood energyEvent horizonElement (mathematics)Goodness of fitCategory of beingLevel (video gaming)Operator (mathematics)Computer animation
12:52
Representation (politics)Dependent and independent variablesSystem callInformationConnectivity (graph theory)Default (computer science)Bit ratePresentation of a groupComputer animation
13:18
Electronic mailing listView (database)Projective planeCodeError messageDependent and independent variablesAreaCASE <Informatik>CodeMeeting/InterviewComputer animation
14:23
Digital filterEvent horizonQuicksortDependent and independent variablesGroup actionOrder (biology)SummierbarkeitWebsiteComa BerenicesRange (statistics)Content (media)CountingMaxima and minimaLink (knot theory)Envelope (mathematics)Rule of inferenceDefault (computer science)Uniform resource locatorEmailCASE <Informatik>Revision controlParameter (computer programming)Field (computer science)Mechanism designInformationWeb pageInclusion mapDependent and independent variablesClient (computing)Query languageInheritance (object-oriented programming)Attribute grammarMobile appResultantRepresentation (politics)Exception handlingSemiconductor memoryEquals signGroup actionSynchronizationPhase transitionRepresentational state transferBuildingCellular automatonSheaf (mathematics)SurgeryForm (programming)FamilyLengthSound effectOverhead (computing)Physical systemLogical constantWave packetArithmetic meanRight angleMathematicsQuicksortSign (mathematics)Multiplication signContext awarenessVector spaceIncidence algebraAuthorizationCovering spaceComputer animation
17:24
Data typeFile formatEmailClient (computing)Server (computing)Telecommunication
17:42
Web browserDependent and independent variablesMessage passingDiagram
18:01
Web browserAddress spaceProper mapLink (knot theory)Cartesian coordinate systemEvent horizonHypermediaConstraint (mathematics)State of matterType theoryStatement (computer science)Vapor barrierRootMultiplication signLogical constantJSONXML
19:09
Dependent and independent variablesTelecommunicationExecution unitCellular automatonGroup actionMereologyCore dumpSoftware developerInformationVideo game
19:42
Software developerState of matterStudent's t-testSoftware bugDemo (music)Point (geometry)Real numberFocus (optics)FreewareView (database)Arithmetic progressionPosition operatorSocial classComputer animation
20:19
Endliche ModelltheorieMereologyGame theoryCodeMultiplication signLoop (music)Image resolutionWeb 2.0Googol
20:55
Dependent and independent variablesLink (knot theory)Multiplication signLevel (video gaming)MereologyDescriptive statisticsSource codeReading (process)Formal languagePoint (geometry)MetadataFigurate number
Transcript: English(auto-generated)
00:00
The next talk will be a RestfulSPI best practices by Malvina, let's give her a big applause. Welcome everybody, I'm Malvina, I'm a developer at AstaX Next, the biggest Python software house in Europe.
00:28
Almost five years ago I wrote my first line of code and that's how my Python journey began. When I'm not hacking, I'm trying to spend time actively at the gym or in the nature.
00:50
Ok, so let's begin with a short story. Some time ago, in one of my previous projects, I had to make many integrations with many providers.
01:04
And each of them had very different level of APIs. We were working on a module which was offering tickets for many kinds of events from many suppliers. At the beginning, we started implementing integrations with the main provider.
01:23
Our first task was to implement a simple search. The end point for searching was limited. The API provider offered us only searching by date or text. So after consultation of our product owner, we decided to develop the same functionality.
01:45
Whilst working on it, we started to get to know better the API and started to see first minor issues. The first surprise was the fact that they didn't have paginations.
02:02
So in result, we had to store all data on client side. Other fact, the documentation was so poor. Besides the fact that it was really hard to find any informations, this information was incomplete. For example, there was no info about return object types, which started to make sense after noticing that the return object types are not consistent.
02:32
Some fields could store none on MTRI, but there was a field that store a datatype object for regular events and string with date range for festivals.
02:46
From our PO point of view, the saddest thing was fact that we didn't display prices on a list view. This information wasn't returned by end point for searching and calling the other end point for all return events would be too expensive.
03:06
So after first sprint, we developed something like this. To check our PO and improve user experience, our next task was enlarging searching.
03:20
We wanted to add filtering and sorting the events. The API provider wasn't offered as such complicated features, so to achieve this goal, we decided to store all data in our database. We developed the cron jobs that were downloading events every day at midnight.
03:43
Additional advantage of this approach was fact that we could also download the prices by calling other endpoints. Every frame seems to go well, but it was a calm before the storm. The problem appeared when all developers and testers started using in on their own local instances.
04:06
It was 8 people. The API provider wasn't prepared for so many codes, so they didn't catch the queries and in result, they banned our IP addresses. After this action, they banned us another couple of times.
04:23
Another visible drawback was fact that they didn't have test environment. The outcome of this was a small disaster. First of all, there was so many fake data on production, like special demo events specially prepared for testing buying the tickets.
04:43
You have to spend a lot of time on their side to find it, whereas on our result page, this data was more exposed. To prevent buying real tickets, our API key was locked. But when we wanted to release our feature, we needed to test buying real tickets.
05:06
So API provider delivered us other unlock API key. Unfortunately, some misunderstanding occurred and they unlocked rank API key. We find it out when a postman came to our office one beautiful day and delivered us a ticket.
05:26
During integration with another providers, the most surprising were URL names. They were very unintuitive. To get the events, you have to go to slash localization endpoints and event endpoints was performances.
05:45
Sorry, I've just lost myself again in the matter of mention of it. Also, data structure was so messy. This API was developed without understanding the client's need. We spent a lot of hours to get the logic and to map the structure of events to ours.
06:10
So the question is, what could the API provider have done better? One of the answers can be RESTful API.
06:22
REST stands for representation state transfer. It's an architectural style with a set of constraints that allows a simple communication between two systems, typically a client and the server, where the communication between these is based on HTTP.
06:41
And now is the question for you guys. Who can name all REST architecture constraints? I thought so. So the formal REST describes six architecture constraints. Clean server architecture style is the basic restriction for RESTful application.
07:02
The system is disconnected. For example, clients are not concerned with data storage and the servers are not concerned with user interface or user state. The purpose of this division is to separate architecture and responsibilities in both environments. In Wizard, we improve the portability of the client's code by simplifying the server's components.
07:29
Statusless is a constraint to the client-server interactions. One client can send multiple requests to the server and each of them must be independent.
07:40
This means that all requests to the server must contain only that information to service the request. In order to improve network efficiency, all returned data from server are explicitly labeled as cacheable or non-cacheable.
08:01
We can cache response messages on client, on the server or above the site. The rule to create a cache can be different for each resources. We can clear the cache after a given period of time or whenever there is a change in some state. Uniform interface is a central feature that distinguishes RESTful architecture styles from other network-based styles.
08:26
It is a well-defined contract for communication between client and the server. The four guiding principles of uniform interface are identifying the resources, manipulating the resources through representations,
08:42
self-descriptive messages, and hypermedia as the engine of application state. The layer system style allows an architecture to be composed of hierarchical layers. There can be multiple layers of software involved in retrieving information.
09:02
Server may improve scalability by adding features like gateway, load balancer, firewall, or by providing shared caches. Code on demand is an optional constraint. Servers can temporarily extend or customize the functionality of clients by transfer of executable code.
09:24
Code on demand typically relies on web browser features like web browser plugins, applets, or client-side scripting languages. Complying with these constraints, REST introduced certain architectural properties.
09:46
Web service APIs that adhere to the REST architecture constraints are called RESTful APIs. Many people would go on to say that have a RESTful API uses only HTTP adjacent, and all of this is important and is part of RESTful itself.
10:03
But to consider an API RESTful, it must strictly follow all the rules designed and defined in REST architecture. It works to be familiarized with Lerna Richardson REST maturity model. A maturity model is a map that guides users into level-increasing levels of compliance with some definition, methodology, or architecture.
10:29
Richardson REST maturity model is the same type of improvement map for building web services. This maturity model knows four levels where the last one designates a truly RESTful API.
10:47
The concept of REST is to separate the API structure into logical resources. Individual resources are identified by URIs. During design, the API resources don't directly map one-to-one your database into resources.
11:08
You don't want to irrelevant implementation details in your API. Use sensible resource names. For example, in our ticketing module, some of the resources could look like this.
11:21
You should notice that all of these resources are nouns, not verbs. Also, don't mix up singular and plural nouns. Keep it simple and use only plural. Use one-case convention. There are three main-case conventions. Common-case, snake-case, and spinal-case.
11:41
As a Pythonist, we would probably pick the snake-case. Also, avoid apostrophes, spacing, and other exotic characters. Resources are identified by URIs and manipulated by HTTP operations.
12:01
Post-get-put-patch-delete corresponds to create, read, update, and delete. So remember, GET methods should not alter the state. To sum up, if you want to retrieve a list of events, use method GET or resource event. To get a specific event, just add id to this resource.
12:22
And if you want to create the event, use PUT method on resource event. To update some event, use PUT or PUT method on the resource of concrete event. And to delete, use method delete. If we have a relations, good practice is to use soup resources.
12:44
But make at most two levels of nested API object. Operations on these resources look the same. Also, you can consider as to your response related resource representations. By default, use only these almost access together.
13:03
Avoid accumulating too much information and don't embed collections if has too many components. By this approach, you then can avoid making extra API calls and improve efficiency. And if that feature would be in API in my previous project,
13:27
you would have had prices on a list view from the beginning and our PO would be happy. To describe return values, our API should return relevant HTTP status codes.
13:41
Of course, we should use this well known. For example, 200 OK can be used to a successful GET. When we create a successfully API should return 201 created.
14:00
Also, in this case, we should add to our response related URL to the just created resource. To handle the errors, also we should use HTTP status codes like here in an example. Also, to inform user what happened, show a useful error message.
14:25
For large datasets, limiting a return amount of data is important. Try to make advanced searching just add query parameters to the URL. If you want to enable filtering, just use attributes name of an equal sign and expected values.
14:43
The sorted results use parameter sorted or ordered by with the name of attributes on which sorting will be performed. The sorted understanding just add hyphen before the attribute name. Sometimes, basic filtering does not fit our needs. Then we should consider providing full text search, querying by multiple fields.
15:06
A nice approach is to enable to sync field which are in response. Clients can save valuable memory by retrieving only needed information. This parent field takes a comma separated fields to include.
15:21
According to the rest theory, actions on resources are constrained to create read update delete. But in real life, there are some cases that doesn't fit this rule. For example, if you want to implement a multi-resource search or compute or convert something,
15:44
for these exceptions you should use verbs as URL names rather than nouns. We should use URL names that are the most fitting.
16:01
But also carefully describe these exceptions in your documentation. It's hard to foresee all resource representations. Almost each app evolves after time. It's natural to version your API. There are many best approaches for versioning APIs.
16:23
The most famous is to include version in URL path. But other piece of world use it by adding version in HTTP header. Oh, and don't invent default versioning.
16:42
Paginate the results to make response easier to handle. Even if at the beginning you don't have large amount of data, you don't know how it will be in the future. And do this in an early design phase is easier. So there's also no one paging mechanism.
17:02
You can add paging to your request by URL or HTTP header. In response, you can return pagination in envelope or header. For example, write or link header. As the result, we can easily navigate through the pages and consume the results.
17:25
Both client and server need to know which format is used for communications. We can use HTTP headers dedicated for this. In content type, define the request format. And accept specified return format.
17:43
In response messages, enable pre-print. It will be easier to debug or analyzing your API through the browser. Try evolving your response messages. In most cases, an unnecessary extra layer in the response messages.
18:03
Hypermedia as the engine of application state is the most omitted constraint. But you should try to use it in your API. Just provide links to your API. If you don't have links in your API, your API still be useful.
18:25
But after providing them, it's more discoverable and self-descriptive. For example, if you want to find Madone concert and some events portal, you have to go to search page, type Madone and pick proper event.
18:44
To do this by your API, first you have to go to documentation and find endpoint for searching. And then you have to do the same to find out how you can display a proper event. And after providing the links, all you need to know to find Madone concert by API is your root address.
19:04
You can interact with API just like you interact with browser. Documentation is an important part of API. It should enhance new commerce and make life easier for current users. So describe all features needed informations.
19:22
Put examples of usage or requests or responses. Use core for this and your API will be easier to debug. Documentation should be easy to find and user-friendly. So try not to use developer jargon and make it pretty.
19:43
From my experience point of view, I have this strange feeling that many developers are in kind of student state of mind. I mean they're not business nor user focused. They forgot the developed feature for real users which is totally opposite to 100% bug free demo path.
20:04
Especially created to satisfy professor needs and pass some classes. And there is a high chance that it will fail each other way. And I'm sure you know what I'm talking about because we all did this. So remember, have a doubt.
20:22
Make sure your code follow the best practices. Even the slightest. Investigate how some part of your API should look like. Check how web giants do this. Use Google search to solve problem or use this issue to initiate the small talk in the kitchen or put this subject in your team.
20:45
Use best practices where they make sense. But of course don't get stuck in an infinite loop of researching best approaches. Think commit and go. The most important part is fact that you are thinking about the user.
21:03
Thank you. We have time for questions. I've got a question. When you talk about links in your API, did you use or is specified anywhere the names?
21:33
The examples of links? The example of links, for example the metadata? Yes, you should use your name and the method.
21:44
And you can also provide a short description about what this link is. Thanks. More questions?
22:01
You mentioned about putting links in the response. I guess that's what you indeed do as best practice. Do you have any recommendation of how nested your response can be? I'm sorry, can you say something louder? You can hear me now? Yes, better.
22:21
I was wondering how nested can a response be? How many layers of nesting you can do? By providing links, yes. By providing links or directly in the response so that you do not have to go to other links? I think that should be at most two levels of nested links.
22:44
But I think that the smartest approach is to you to pick the proper one which is the links which be the most uses from this point of response.
23:12
Anyone? No more questions? Thanks, Marbina again.