22 Thursday Dec 2022
Posted in ExternalWebPublications, General, Technology
Tags
API, book, Cloud, DevRel, external, external publications, Notification, OCI, Oracle, Queue, SEDaily, Software Engineering Daily
We haven’t blogged too much recently as we have been busy helping get and producing content for my employer Oracle, working with Software Engineering Daily, and developing a collaborative book. So, I thought I’d pull together some links to these new resources.
Continue reading14 Wednesday Dec 2022
Posted in APIs & microservices, development, General, Technology
One area of API design that doesn’t get discussed much is the semantics of the payload. That is, the names we give our attributes and elements for the values being communicated. When developing single-use APIs (usually for client applications), this is unlikely to be an issue as the team(s) involved are likely to know each other and are able to interact and resolve clarity issues easily enough (although getting the semantics right makes this easier particularly in the long term). But when it comes to providing reusable endpoints, we may know the early adopters but are unlikely to interact with consumers beyond that unless there is a problem.
This makes getting the semantics right somewhat harder. How do we know if our early adopters represent the wider customer base (internally and externally)? Conversely, if we simply use our own company terminology, how do we know that it is representative of the wider user base? It isn’t unusual for organizations to develop their own variations of a term or apply assumed meaning. Even simple things, a ‘post code’ element of an address, other parts of the world use ‘zip codes’ or PINS are they the same? Perhaps if we said ‘postal code,’ we break the direct specific country associations with ‘post code.’ We can overcome these issues by providing a dictionary of meanings and lengthy explanations. Using the right term goes beyond simply understanding the data value; it will infer specific formatting and potential application behaviors. Taking our postcode/zip code example. In the UK data is published, which means it is possible to easily validate a postcode against the address line and vice versa. In fact, in the UK to get something delivered, you only need the property number and the postcode. A US 5-digit zipcode can’t do that. For that precision, the ZIP+4 needs to be used.
If we can address these issues, then life becomes easier for us in maintaining the information and for consumers in not needing to look up the details. The question is how can we be sure of using semantics that is consistent across our APIs and widely understood and, when necessary, already documented, so we don’t have to document the information again?
Read more: API payload design getting the semantics rightThere is a shortcut to some of these problems. Many industries have agreed on data models for different industries. The bodies such as OASIS, OMG, and others are developed and maintained by multiple organizations. As a result, there is a commonality in the meaning achieved. So if you align with that meaning, then use that semantic. Not only can the naming of attributes become easier, but any documentation can be simplified to reference the published definitions. in most cases, these standards are publicly available as it promotes the widest adoption – one of the goals of developing such models. But there are some pitfalls to be mindful of using this approach:
Some organizations, such as TMForum have taken the public data model to the next step and provided predefined API specifications. This is ideal where you’re following industry standards and providing standardized/common services that aren’t a differentiator but need to be offered as part of doing business.
Larger, data-mature organizations will keep some form of Data Catalog. These catalogs are often held to help understand compliance needs, such as where personal data is held, how data issues can impact data accuracy and integrity, etc. It is possible that metadata may also be kept to address the semantic meaning of data or reference the definitions. Such information is used to help inform any data cleansing that may be needed. This offers a potentially good source of information for internal API use cases.
If your business is delivery/service focussed so that your unique value isn’t in IT processes but perhaps something that the company manufactures or a specialist service such as consulting in a specific industry, then it is possible that the majority of your systems are SaaS or COTs based. If your business has opted to focus on a particular vendor, e.g., Oracle or SAP, for most services, then vendor-led data models are a possibility. These vendors are often involved with public data model development, so they won’t be too divergent in most situations – but awareness of differences is necessary, but as both models should be internally consistent, the differences will also be consistent. This approach will give you better alignment and reduce the chances of needing to address any divergence. The downside of this is a change of direction on strategic vendors can create additional work going forward as the alignment is disrupted. More work will be needed to map from your naming and semantics to the new core, and attempts to move away from the selected model to try to realign semantics with a new core will potentially create breaking changes for API consumers.
Regardless of the approach taken, there are some very simple but critical rules that will keep you in a good place:
Regardless of approach – be careful not to lock your API semantics and data model to that of the storage layer – these can change and even create breaking changes that you shouldn’t expose to your users. Some sources to consider.
Some more reading on the subject:
10 Thursday Nov 2022
Posted in Books, General, Technology
Tags
API, books, manning, Packt, Presentation
Today I was fortunate enough to present at one of the Cloud Lunch and learn events (you can register for any of the events here and see previous sessions here). One of the questions asked at the end of the session was recommended reading on APIs. So I’ve gathered up some links to books I’d suggest worthwhile reading I’d suggest:
I should also mention an API book I’ve co-authored. While it focuses on an Oracle product, there is a lot of content that is relevant to any API development using an API Gateway (Amazon.co.uk). I’ve not looked at all the books at API-University, but from I have seen the content is worth examining.
The slides for my presentation can be found on slideshare, and here:
The Presentation recording can be found here:
Continue reading15 Thursday Sep 2022
05 Friday Aug 2022
Posted in APIs & microservices, development, General, Technology
Tags
API, architecture, code, GraphQL, gRPC, Oracle, streaming, subscriptions
Yesterday I was fortunate enough to participate in the Dev Innovation summit part of the World Festival virtual conference.
The presentation took a look at how Streaming APIs offer an alternative to API polling and the considerations needed when adopting streaming.
Continue reading16 Thursday Jun 2022
Posted in development, General, languages, node.js, Technology
Tags
API, code, development, GraphQL, javascript, node.js, Technology
I’ve designed a variety of GraphQL schemas and developed microservice backends. But not done much with configuring the Apollo implementation of a GraphQL server until recently. This may reflect the fact my understanding of JavaScript doesn’t extend into the world of Node.JS as much as I’d like (the problem with being a multi-language developer is you’re likely to find your way around many languages but never be a master of one). Anyway, the following content is about the implementation within a GraphQL server part of a solution. It may be these pointers are just for my benefit you might find them helpful as well.
To make it easy to reference the code, we’ve added entries (n) into the code, where n is a number. This is not part of the code. But there to make the different lines referenceable. Where code should go but is not relevant to the point being made I’ve added ellipsis (…)
import { ApolloServer } from 'apollo-server';
import { loadFilesSync } from '@graphql-tools/load-files';
import { resolvers } from './resolvers.js'; (1)
import ProviderInternalAPI from './ProviderInternalAPI.js'; (1)
import EventsInternalAPI from './EventsInternalAPI.js'; (1)
const server = new ApolloServer({
debug : true, (2)
typeDefs: loadFilesSync('./schema.graphql'), (3)
resolvers,
dataSources: () => {
return {
eventsInternalAPI: new EventsInternalAPI(), (4)
providerInternalAPI: new ProviderInternalAPI() (4)
pro
};
}});There is the potential to dynamically load the resolvers rather than importing each JavaScript file as we see on lines (1). The mechanics to do this is documented here. It would be cool if an opinionated implementation was provided. As shown by (3) we can take a independent schema file being loaded. The Apollo example approach for this didn’t seem to work for us, although both approaches make use of graphql-tools in a synchronous manner.
We can switch on debugging (2) for the GraphQL server, although the level of information published doesn’t appear to be significant. Ideally this setting is changed for production.
The prefix for each resolver (1) must correlate to the name in the schema of the mutator or query (not the type as you would expect with Java). Often we don’t need all the parameters for the resolver. The documentation describes replacing each unused parameter with one or more underscores (i.e _, __ ). The underscore denoting the field not in use. However we can satisfy the indication of not being used, but keep the meaning of each position by using the underscore then a name (i.e. _parent, _args ) as shown in (2).
By taking the response into a variable (3) we can optionally log it. Trying to return using invocation line would result in the handler object rather than the payload itself. By taking the result into a variable we can log the content if desired and return the content.
The use of the backward quote is a node feature. It allows us to incorporate variables into a string by referencing it within ${} (4).
We need to supply the GraphQL server with instances with a layer of code that will interact with the resolvers. We can instantiate the instances in the declaration. The naming of the object is important (4) to the resolver.js (declarations).
import { useLogger } from "@graphql-yoga/node";
...
latestEvent (1): async (_parent, _args, { dataSources }, _info) (2) => {
if (log) { console.log("resolvers - get latest event"); }
let responseValue = await dataSources.eventsInternalAPI.getLatestEvent(); (3)
if (log) { console.log(`(4) Resolver response for latest event:\n ${responseValue}`); }
return responseValue;
}, Query: { ...
},
Mutation: {...
},
Event: { (1)
providers: (event, args, { dataSources }, info) => {
if (log) { console.log(`going to locate ${event.sources}`) }
let responseValue = await (2) dataSources.providerInternalAPI.getProviders(event.sources);
return responseValue;
}To handle the use of resolvers within a larger resolver we need to declare the resolution outside of the Query and Mutator blocks (but inside the whole declaration block)(1). The name provided needs to match the parent entity that the query resolver contributes to.
To then provide values from the outer resolution we need to prover to the chained resolution use the naming as represented in the GraphQL schema as shown by (2). The GraphQL engine will resolve the mapping values.
// GET
async getProvider(code) {
console.log("getProvider (%s) directing to %s",code,this.baseURL);
return this.get(`provider?code=${code} (1)`);
}The URL parameters need to be appended to the base URL path for the parent class to use in the invocation as shown by (1). The Apollo examples showed a setter option but we didn’t see the URI being addressed properly. This approach produces the relevant requirement.
01 Tuesday Mar 2022
Posted in APIs & microservices, General, Technology
I got into a discussion with several people about the use of GraphQL and related API technologies and discovered that a presentation I’ve been using and evolving for a while now, didn’t appear in my blog. So here is a version of it used at an API Conference …
The presentation may appear again in the future as the perspective of API technologies evolves the presentation will need to evolve. For example, AsyncAPI is starting to make an impression now. Other variants to API technologies such as DRPC are showing up.
If you’re new to GraphQL you might find a couple of other posts on the subject helpful:
19 Friday Nov 2021
Posted in General, Technology
Tags
It has been a busy week with the day job of delivering to customers, with a webinar with Oracle, Flexagon and a customer – Heathrow Airport. Plus two technical sessions for DOAG.
The webinar is the latest step in the partnership between Capgemini and Flexagon. If you’d like to see it, the recording can be accessed here.
The webinar development was very much a team effort with Oracle providing the hosting and promo logistics (particularly from Jurgen Kress and input from Daryl Eicher). Presentation development effort with Flexagon (Dan Goerdt and Tanya O’Connor). Of course the great input from our Heathrow customers – Mark South and Nick Byng-Maddick.
We have another blog post related to the webinar sharing some more detail. This will be published in a week or so on blog.oracle.com.
The Deutsche Oracle Anwendergruppe (DOAG) conference took place virtually this week. DOAG and the UKOUG events are probably the biggest of the European user group events. With UKOUG happening at the end of the month.
My presentations at DOAG have been an update on which GraphQL, gRPC or REST API technology to use (see the presentation material here), along with a brand new presentation, again relating to APIs. But this time we’re looking at the application and capabilities of the Oracle Cloud’s API which can allow us to manage a wide range of services (see here). While I don’t have the demo piece recorded, you can see the slide aspect here.
As mentioned I will be presenting at UKOUG Together. I have another brand new presentation for this as well, which will look at GitHub Actions combined with Oracle Cloud. We also have our first 2022 conference confirmed, in the form of API World.
31 Sunday Oct 2021
Posted in APIs & microservices, General, Technology
Tags
API, apiary, APIWorld, car, conference, Hospitality, Mercedes, Nordic API, OHIP, Oracle, photoss, Postman, presenting, REST, Walgreens
I recently presented at APIWorld about how API definitions go beyond the payload specification into providing details of terms and conditions and so on. You can see the presentation here (more about my presentations here).
One of the questions during the presentation did I have other examples of good APIs, reflecting the points I’d made. A very valid question, to which I didn’t have more examples to hand, hence this post.
So the easy answer would be to point to an excellent article on Nordic APIs (here) that address the question and explain why they rate the APIs. But that’s a little bit of a lazy answer and in all fairness, the examples provided are from organisations where APIs are recognised as a primary or important contributor to business revenue. So I’ve looked at areas where the API may not necessarily be seen by the business as the primary source of revenue. With the examples provided, we’ve described what we think is good, or not so good about them. Hopefully, through these examples, you’ll see why points are made in the presentation. So here are my reviews…
Continue reading21 Monday Jun 2021
Posted in APIs & microservices, General, Oracle, Technology
Phil (aka MP3Monster)'s Blog 
You must be logged in to post a comment.