Continue from the API canvases and value proposition towards designing the proper interfaces.
How to use the Data requirements -template
Start with the top 5 concepts, then continue to validate them with the questions
Start with the top 5 concepts, then continue to validate them with the questions
The top 5 concepts are logical concepts, usually nouns, that make up the core of the API under design. For example, products, customers, ingredients, and locations are core concepts for a food delivery API.
Sometimes you will notice at this stage, what you thought would be one API or one endpoint, is actually splitting into several.
After you have the initial core concepts, start working your way clockwise in the template.
"What questions the API consumers need answers to?"
Write down questions like "What products can be delivered to my location in under 30 minutes?". These will form the bases of your GET-requests, in this case for "products" -resource aka. endpoint. Your variables will be location (possible address or geolocation) and delivery time (in minutes). Your response will contain a list of products, that you have to identify somehow.
"International, national, industry specific or company wide data standards?"
You already identified products, location and time as concepts. What regulations or standards are related to these, for example ISO-standards or legal requirements? Good starting point are the schemata in schema.org where most concepts have been described as a ready made schema with examples and proper standards.
Products is a notoriously tricky concept for standards, because each industry has it's own set of standards for products, even though there are some globally standard identifiers.
"Common identifiers and required attributes?"
The products and locations need to be identified, for sure. But how? Location for example can be stored as co-ordinates or with address schema containing street address and ISO code for country.
Which attributes do you have to really have to ask the question? Do you always have to give location? Probably. But what about the delivery time? Is some default time used, if it isn't given?
What about the response? What is the minimum information needed about products in this case. Is it enough to return identifier, or should you also include product name in the response to make it easier to the client consuming the API. This is ok for GET requests, but do we also offer an API endpoint for creating products or orders? What are the minimum requirements then?
"How fresh the data needs to be?"
How fresh is fresh data is always a relative question. In this example case all we know is that the food delivered as a result of the API must be fresh. The list of products might be quite stable, but the availability and queue size of orders waiting to be delivered might vary. Is 5 minutes enough or should it be 30 seconds or 5 seconds? All of these options have different requirement on integrations, humans updating the information or processing the queue and the customer experience.
How to use the Request & Response -template
Request & Response is the typical pattern for any APIs, including REST APIs. It may not always be the most efficient, though.
A lot of polling is needed to keep the data fresh, because the API consumer won't know if the data has changed in the API provider side.
Start from the left-top corner by designing the request and then design the right-bottom corner, the response.
What needs to be done in the middle to perform the request and clean the response, depends on the systems and data sources involved.
Use bullet points and example data to describe the attributes needed for the request. Dissect the questions from the Data requirements -template as requests (one question should be one request).
Also creating or updating data requires a request, but move to this after processing the questions (the GET -requests) first.
Use bullet points and example data to describe the attributes needed for the response. Describe what the response will contain. Remember the response is the "answer" to your "question" set in the request.
In case the request contains data to be created or sent for processing or updates, the response is possibly empty or contains only an identifier.
The systems, data sources and algorithms, possibly even other APIs that need to be used to handle the request.
Because we are still on the business language and logical level, write the processing rules in a human language sentence: "Check which cooks have an order queue that will empty in given amount of minutes (deadline) and what products (pizza, pasta, chinese) are they able to make?"
This step is about cleaning the values and combining different data sources so that the performed results can be sent as response. This step can be optional, depending on need. Use it in situations where it's clear that some identifiers, categories or for example time stamps coming from the underlying systems or logic need some standardizing or cleaning up. Use this step also to describe filtering out data and operations due to access rights of the user.
How to use the Events -template
The events (or push or hooks) -template is used for a subscription based model where the API provider will inform the API consumer when some condition is met and data or state is changed.
Request subscription (at the top) is done once, when the API consumer subscribes to hear about specific events.
Process event layer (middle) is for describing triggers and processing rules for specific event, for example when product delivery is confirmed.
Subscription removal (bottom) is used for describing how the subscription is removed when the API consumer no longer is interested in the events.
SECTION 1 - WHAT DO WE DO WITH YOUR INFORMATION?
When you browse our website, we automatically receive your computer’s internet protocol (IP) address in order to provide us with information that helps us learn about your browser and operating system.
With your permission, we may send you emails about our site, new services, events and other updates.
SECTION 2 - CONSENT
How do you get my consent?
When you provide us with personal information to complete a transaction, verify your credit card, place an order, arrange for a delivery or return a purchase, we imply that you consent to our collecting it and using it for that specific reason only.
If we ask for your personal information for a secondary reason, like marketing, we will either ask you directly for your expressed consent, or provide you with an opportunity to say no.
How do I withdraw my consent?
If after you opt-in, you change your mind, you may withdraw your consent for us to contact you, for the continued collection, use or disclosure of your information, at anytime, by contacting us at [email protected]
SECTION 3 - DISCLOSURE
We may disclose your personal information if we are required by law to do so or if you violate our Terms of Service.
SECTION 4 – SERVICE PROVIDERS
Our website is hosted on Strikingly Inc., a Delaware, US based company. They provide us with the website platform including the subscription and web form data you submit to us.
We use Google’s application suite for email, documents and calendar and Campaign monitor for sending email campaigns. We only allow dedicated personnel to get access to these systems. Emails sent to our general email [email protected] are also stored in PlanMill, our ERP system, for customer service and archiving.
SECTION 5 - THIRD-PARTY SERVICES
In general, the third-party providers used by us will only collect, use and disclose your information to the extent necessary to allow them to perform the services they provide to us.
However, certain third-party service providers, such as payment gateways and other payment transaction processors, have their own privacy policies in respect to the information we are required to provide to them for your purchase-related transactions.
For these providers, we recommend that you read their privacy policies so you can understand the manner in which your personal information will be handled by these providers.
In particular, remember that certain providers may be located in or have facilities that are located a different jurisdiction than either you or us. So if you elect to proceed with a transaction that involves the services of a third-party service provider, then your information may become subject to the laws of the jurisdiction(s) in which that service provider or its facilities are located.
When you click on links on our store, they may direct you away from our site. We are not responsible for the privacy practices of other sites and encourage you to read their privacy statements.
SECTION 6 - SECURITY
To protect your personal information, we take reasonable precautions and follow industry best practices to make sure it is not inappropriately lost, misused, accessed, disclosed, altered or destroyed.
SECTION 7 - COOKIES
You are asked separately for accepting cookies on the site.
SECTION 8 - AGE OF CONSENT
By using this site, you represent that you are at least the age of majority in your state or province of residence, or that you are the age of majority in your state or province of residence and you have given us your consent to allow any of your minor dependents to use this site.
If our store is acquired or merged with another company, your information may be transferred to the new owners so that we may continue to sell products to you.
QUESTIONS AND CONTACT INFORMATION
If you would like to: access, correct, amend or delete any personal information we have about you, register a complaint, or simply want more information contact our Privacy Compliance Officer at [email protected]